Skip to content

Creating a URL

Jump to bottom
Frizzle edited this page Jun 3, 2026 · 5 revisions

Creating a URL Scheme for Nightflix Integration

Overview

Nightflix uses TMDB to display movies and series and allows users to choose a streaming provider to watch content. To integrate, providers must supply deep links that open their app or website to the correct movie or episode when triggered from Nightflix.

This guide explains how to create a compatible URL scheme, implement deep linking, and ensure proper compatibility with Nightflix across iOS, Android, and web platforms.

Understanding Deep Links

Deep links allow users to open specific content inside an app instead of only launching the home screen.

Example:

yourservice://movie/12345

When the user taps this URL, your app should immediately open the selected movie.

Nightflix relies on deep linking to redirect users from the Nightflix interface to the provider’s playback page or app.

Types of Supported Links

Custom URL Schemes

Custom URL schemes use a unique protocol registered by your app.

Example:

yourservice://movie/12345

Advantages:

  • Simple to implement

  • No backend setup required

  • Works directly with installed apps

Disadvantages:

  • No automatic fallback if the app is not installed

  • Potential conflicts with other apps

  • Less reliable on some platforms

Universal Links / App Links

Universal links use standard HTTPS URLs tied to your app.

Example:

https://yourservice.com/movie/12345

Advantages:

  • Opens the app if installed

  • Falls back to the website automatically

  • More secure

  • Recommended by Apple and Google

Disadvantages:

  • Requires backend configuration

  • Requires domain verification files

Nightflix strongly recommends supporting universal links in addition to custom schemes.

Nightflix Compatibility Requirements

To work properly with Nightflix, providers should:

  • Support direct deep linking to movies and episodes

  • Maintain a mapping between TMDB IDs and provider content IDs

  • Support both app-based and browser-based opening

  • Avoid login redirects whenever possible

  • Ensure links remain stable over time

Recommended Link Structure

Movies

yourservice://movie/<providerMovieId>

or

https://yourservice.com/movie/<providerMovieId>

TV Series

yourservice://show/<providerShowId>

or

https://yourservice.com/show/<providerShowId>

Episodes

yourservice://show/<showId>/episode/<episodeId>

or

https://yourservice.com/show/<showId>/episode/<episodeId>

TMDB ID Mapping

Nightflix identifies content using TMDB IDs.

Providers must internally map TMDB IDs to their own catalogue IDs.

Example:

TMDB ID | Provider ID -- | -- 603 | matrix-1999 550 | fight-club

When the user presses play, Nightflix uses this mapping to generate the final deep link.

Implementing a Custom URL Scheme

iOS

In Xcode:

  1. Open your project settings

  2. Go to:

    • Info

    • URL Types

  3. Add your scheme

Example:

yourservice

Your app should then handle incoming URLs and navigate to the correct content page.

Android

In AndroidManifest.xml, add an intent filter:

<intent-filter>
    <action android:name="android.intent.action.VIEW" />

&lt;category android:name="android.intent.category.DEFAULT" /&gt;
&lt;category android:name="android.intent.category.BROWSABLE" /&gt;

&lt;data android:scheme="yourservice" /&gt;



</intent-filter>

Your app should parse the incoming URL and open the requested content.

Implementing Universal Links

iOS Universal Links

Requirements:

  • HTTPS domain

  • apple-app-site-association file

  • Associated Domains entitlement

Example:

https://yourservice.com/movie/12345

Android App Links

Requirements:

  • HTTPS domain

  • assetlinks.json

  • Intent filters configured for HTTPS

Example:

https://yourservice.com/movie/12345

Recommended Fallback Behavior

If the app is not installed:

  • Open the provider website

  • Redirect to the App Store or Play Store

  • Show a valid content page instead of a generic homepage

  • Avoid dead links and 404 pages

Best Practices

Keep URLs Stable

Do not frequently change link structures. Stable URLs improve compatibility and reduce broken links.

Avoid Authentication Walls

Whenever possible, allow the content page to load before requesting login.

Support Web Playback

Some Nightflix users may prefer browser playback instead of app launching.

Use HTTPS

Always use HTTPS for universal links and web playback.

Handle Invalid IDs Gracefully

If content no longer exists:

  • Show an error page

  • Suggest similar content

  • Avoid crashes or blank pages

Testing

Providers should test:

  • Installed app behavior

  • Non-installed app behavior

  • Browser fallback behavior

  • Login-required behavior

  • Different OS versions

  • Different browsers

Example Integration Flow

  1. User selects a movie in Nightflix

  2. Nightflix reads the TMDB ID

  3. Nightflix maps it to the provider content ID

  4. Nightflix generates the provider deep link

  5. The provider app or website opens directly to playback

Security & Compliance

Providers are responsible for:

  • Their own content

  • Copyright compliance

  • Streaming legality

  • User authentication systems

Nightflix does not host, upload, distribute, or provide copyrighted media files. It only redirects users to provider platforms through deep links.

Conclusion

A good deep-linking implementation makes playback seamless and improves the overall Nightflix experience.

Providers should:

  • Support direct movie and episode links

  • Implement universal links

  • Maintain TMDB mappings

  • Ensure reliable fallback behavior

  • Keep URLs stable and documented

Following these guidelines ensures smooth compatibility between Nightflix and your streaming platform.

Clone this wiki locally