Deferred deep links

When someone opens a link without your app, installs it from the store and launches it, your app can still take them to the link's destination. Deep Blue Links supports two ways to find that link.

Android: the install referrer

Every Google Play URL the preview page opens carries the short link in its referrer parameter, as link= followed by the encoded short URL. After the install, the Play Install Referrer API gives your app that referrer, decoded once:

link=https%3A%2F%2Fdemo.dev.thedbl.ink%2FXy3kP9aQ

Parse it as a URL query string, read link, and send it to POST /api/links/resolve. The match is exact, with no time window and no guessing, so an Android app that reads the referrer doesn't need check-deferred. The Android guide shows the code.

Other platforms: matching the click

On its first launch after an install, your app calls POST /api/links/check-deferred with its API key, the device's IANA timezone and, when it can, a few device readings:

{
  "timezone": "America/Chicago",
  "device": { "screenWidth": 1179, "screenHeight": 2556, "language": "en" }
}

When Deep Blue Links can tell which of your links the user opened before installing, it answers with that link, as resolve does. When it can't, it answers 404 and your app opens normally: no link is better than the wrong one. Call it once, on the first launch after an install, and store a flag so later launches skip it.

Device readings

• Screen: the width and height in physical pixels, which is points times the screen scale, in either orientation.
• Language: the device's language, such as en-US.

device is optional, but it makes the match more reliable where many people share one connection, such as an office or a mobile carrier, so send it on iOS. On Android, read the install referrer instead: Chrome reports the screen in a way that can differ from the app's own pixel count.

When a click can't be matched

A deferred link works when the user installs and opens your app soon after tapping the link, on the same connection. There's no match when:

• The install and first launch take longer than an hour.
• The device changes network between the tap and the launch, such as from Wi-Fi to mobile data, or turns a VPN on or off.
• Safari opened the link through iCloud Private Relay.

In those cases check-deferred answers 404, and your app opens normally.