Home · Blog

3 September 2026 · updated 9 September 2026 · 11 min read

How Apple TV deep linking actually works

One press that opens Max at a specific film looks like magic and is really a short string of text handed from one app to another. Here is the whole mechanism, including the parts that fail.

An app can ask tvOS to open a URL

Every app on an Apple TV runs in its own sandbox and cannot reach inside another app. What it can do is ask the system to open a URL. The system looks at that URL, works out which installed app claims it, and switches to that app, handing it the URL as it launches.

That is the entire trick. The app doing the sending never controls what happens next — it hands over a string and the receiving app decides what to make of it. If the receiving app understands the string, you land on a film's page. If it does not, you land wherever that app opens by default, usually its home screen.

Two kinds of link, with different failure modes

Custom URL schemes

An app can register a private scheme — a prefix before the colon that belongs to it rather than to the web. When the system sees a URL starting with that prefix, it launches the owning app. Schemes are simple and fast, and they are also completely undocumented in most cases: they are an implementation detail the service can rename in any release, and there is no public registry that says which prefixes exist or what paths they accept.

Universal links

The other kind is an ordinary https:// web address that the app has claimed. A service publishes a file on its own domain declaring which of its app identifiers may handle which paths, and the device checks that file. When the claim holds, opening the web address opens the app instead of a browser.

Universal links are the better-behaved option, because the claim is verified by the service's own server and the address is one you can also open on a phone or a laptop. On tvOS there is a wrinkle: there is no browser to fall back to. On a phone, an unclaimed universal link opens Safari and you still reach the film. On an Apple TV, if the app does not claim the link, nothing useful happens at all.

Why you cannot look this up

There is no directory of streaming deep links. Services publish link formats for their own marketing, partners get formats under agreement, and everyone else infers them. Two apps from the same company can behave differently on tvOS and on iOS. The same app can behave differently in two countries, because the identifier a link carries may be regional.

This is why the only honest way to know whether a link works is to send it to a real Apple TV, with that app installed and signed in, and watch the television. Not a simulator — the simulator does not have the streaming apps.

So we measured it, one URL at a time

Everything above is how the mechanism is supposed to work. What follows is what an actual television actually did. The rig was a physical Apple TV 4K running tvOS 26.6, tested on 26 August 2026, with each service's app installed and signed in, sending one URL at a time and writing down the result. No simulator: the simulator has no streaming apps and never will, because App Store binaries cannot run on it.

Custom URL schemes are largely dead

Max was installed and running. It answered false to canOpenURL for every scheme it has ever shipped under any of its names:

The obvious suspicion is a mistake at our end — a missing declaration, a malformed URL. Two controls rule it out. plex:// and youtube:// both answered true on the same box in the same run, and both were installed. The mechanism works; Max simply no longer answers to any of its schemes.

Universal links are what actually works

So the service whose seven custom schemes were all dead was reachable the whole time over https. Any service whose search rung was built on a custom scheme had no working search at all, which is a silent, total failure that looks exactly like the feature not existing.

canOpenURL cannot be trusted for https on tvOS

This is the finding that shapes the most code. On tvOS, canOpenURL returns true for any https URL, whether or not anything on the box can handle it — because on a phone there is always Safari to catch it, and on an Apple TV there is no browser to fall back to, so the question has no meaningful answer. Only actually calling open reports the truth, and by then the user has already pressed the button.

The consequence is that a button cannot honestly label itself by asking the system what will happen. It has to remember what happened last time. That is why JumpIn's button text is derived from recorded outcomes rather than from a capability check.

The mistake that cost two days: AASA matches on path only

A service's apple-app-site-association file claims paths, and a query string is not part of a path. So /search?q=Inception has the path /search, and will never match a claimed pattern of /search/*. We spent two days concluding deep links were impossible on the strength of a rule we had misread.

The failure that looks like the user's problem

A custom scheme that is not declared in the sending app's LSApplicationQueriesSchemes makes canOpenURL return false silently — indistinguishable from the app not being installed. An entire fallback ladder can collapse into "you don't have this app" because of one missing line in a plist. JumpIn has a unit test that fails the build if any scheme in its catalogue is missing that declaration.

What that leaves

This table is a snapshot, not a contract. Schemes are undocumented and change without notice, services reassign identifiers, and a link that works in one country may not in another. It was true on 26 August 2026 on tvOS 26.6. The correct way to treat any published deep-link table, including this one, is as something that has to be re-measured rather than trusted.

What "it did not work" actually looks like

Deep links do not fail loudly. They have three failure shapes, and telling them apart matters if you are trying to fix one:

• The app opens at its home screen. The system found the app but the app did not recognise the path — usually because the format changed, or the identifier in the link is not the one that service uses in your region.
• Nothing happens. No app claims the URL. On tvOS, with no browser to catch it, the press appears to do nothing at all.
• The App Store opens. The app is not installed. This is the one genuinely helpful failure, and only if the sending app deliberately arranged it as a fallback.

A well-built link opener checks whether an app is installed before it promises anything, and degrades in a stated order: exact title, then app home screen, then the App Store page for the app. What it should never do is promise the title and silently deliver the home screen.

Some apps accept nothing at all

The uncomfortable part of this topic is that deep linking is a courtesy, not an obligation. A streaming app that does not want to be launched into by third parties simply does not claim any links, and there is no technical route around that. No amount of cleverness in the sending app can create an entry point the receiving app has not built.

Netflix's Apple TV app is the case people notice, because it is often the service a title turns out to be on. It accepts no incoming links, so the best any app can do is open Netflix and let you search there. The right response to that is not to pretend otherwise — it is to say "opens the app" on the button before it is pressed.

The other route: Apple's own integration

Separately from all of this, Apple runs a partner integration behind universal search and the Apple TV app's "Ways to Watch" row. Participating services hand Apple catalogue metadata and playback entry points, which is why some titles play from Apple's own interface without you ever seeing the other app's home screen. That path is closed to third-party apps — it is a business arrangement between Apple and each service, not an API, and it covers only the services that signed up. When people say universal search "does not find Netflix", this is the mechanism they are bumping into.

How JumpIn handles it

JumpIn keeps a table of link formats per service and per region, and treats every entry as unverified until it has been watched working on a real Apple TV. Verified entries get the strong promise; everything else gets the weak one. The button text is the contract: it tells you whether you are about to land on the title or on the app's front door, before you press it.

You can see the full ladder of what opens where on the JumpIn home page, or read how to find which streaming service has a movie for the step that comes before the press. JumpIn is on the App Store for Apple TV.

Practical follow-ups. For the everyday version of this, see Apple TV search and remote shortcuts worth knowing and how to keep a watchlist that survives across services, or work out what to cancel with the streaming subscription audit.