Deep Link Reference

Overview

You can use deep links for your Journeys, Ads Links, Quick Links, and Email. Use this reference article to help you configure your default and custom link behavior.

Read our Create Web Links or Create App Links articles for instructional content on creating links using different methods.

In this reference article, you can learn about:

Note
Information about web links in this article is only relevant for the Engagement product, read our Create Web Links article for web links information relevant to the Activation product.

Create deep links

You can create both web and app deep links with the Branch Growth Platform. Links can be either short or long.

Short links

Short links are the most common deep links created via the Branch SDK or Deep Linking API. You can use a Branch-provided app.link, or use a custom domain (for example, links.yoursite.com). You can tailor the appearance of the shortcode to a custom alias during creation. Aliases can be short strings (for example, https://example.app.link/october-sale),or can be a full link path (for example, https://example.app.link/product/id1234 ).

Short links contain link data inside them on link creation (for example, existing link https://example.app.link/fzmLEhobLD ). Short links can also have additional data appended to them (for example, dynamic link https://example.app.link/fzmLEhobLD?content_id=123 ).

Methods of creating short links

Check out our Create Web Links and Create App Links articles to learn more about creating short links.

Long links

Long links can be created without a network call to Branch. Long links need link data to be added as a query string. Be sure to URI encode any URLs in the link.

Existing link example: https://example.app.link/fzmLEhobLD?foo=bar&baz=456&$fallback_url=https%3A%2F%2Fbranch.io%2F or
Dynamic link example: https://example.app.link/?foo=bar&baz=456&$fallback_url=https%3A%2F%2Fbranch.io%2F .

Long links need a /a/ and a Branch Key if you use a custom domain.

Existing link example: https://link.example.com/5NPh/p4M09KRLrD?foo=bar&baz=456&$fallback_url=https%3A%2F%2Fbranch.io%2F
Dynamic link example: https://link.example.com/a/key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt?foo=bar&baz=456&$fallback_url=https%3A%2F%2Fbranch.io%2F

When adding tags to a dynamic link, enter each tag separately. For example: https://example.app.link/?foo=bar&~tags=tag1&~tags=tag2 .

Validate deep link behavior

Use the Link Validator to view the expected and actual behavior of your links.

Expand to view information about expected link behaviors

Default link behavior

If your user does not have your app installed:

User clicks on a Branch deep link.
Device navigates to the fallback (for example, an app store or website).
- We support the following app stores:
  - Apple App Store
  - Google Play
  - Huawei App Store
  - Vivo App Store
  - Oppo App Store
  - Baidu Mobile Assistant
User installs and opens your app.
Branch passes deep link data into your app.

If your user does have your app installed:

User clicks on a Branch deep link.
Device opens your app or navigates to expected link behavior.
Branch passes deep link data into your app.

Custom link behavior

Pass data from link to app

Add link data to each deep link.
Add key-values pairs to your Quick Links.
Append query strings https://example.app.link/fzmLEhobLD?$custom_data=123&hello=world .

Fallback to a specific URL

Determine where a deep link will navigate to if either
- Your app is not installed
- [or] Another app prevent links from deep linking outside their app
Fallback overrides (ordered by precedence)
- Add query string https://example.app.link?$ios_url=https://example.com
- Add link data $ios_url = 'https://example.com' (docs)
- Add link data for a deep view $ios_deepview = 'deepviewId' (docs)
- Enable a Deep View globally on the Branch Dashboard
- Add link data $fallback_url = 'https://example.com' (docs)
- Add iOS/Android Custom URL on the Branch Dashboard
- Add Default URL ($fallback_url) on the Branch Dashboard

Open web instead of app

Note
This information is only relevant to the Engagement product. Activation links do not require /e/ or -web to open in a web browser.

If your app is not installed: device navigates to the fallback (for example, an app store or website).

If your app is installed:

- iOS: need to override Universal Links
  - Add $web_only = true (docs).
  - Add redirect $ios_url = 'https://google.com' (docs).
  - [or] Append /e/ to the deep link.
    - e.g. https://example.app.link/fzmLEhobLD -> https://example.app.link/e/fzmLEhobLD
- Android: need to override App Links
  - Uncheck Enable App Links and then hit Save on the Branch Dashboard.
  - Add redirect $android_url = 'https://google.com' (docs).
  - Add a broken URI Scheme with $android_deeplink_path = 'random' .
Add -web in the link domain: e.g. branch.app.link -> branch-web.app.link .
- Does not work with custom link domains when used in conjunction with a custom alias.

Social link behavior

Use OG Tags to display content as a preview card in Facebook, Twitter, Pinterest, iMessage, etc.
- The $og_title and $og_description tags are included with the Branch Growth Platform.
- The $og_image_url tag is reserved for paid Branch accounts with a dedicated contract.
Use Deepviews to display content as a website.
- Increases install attribution.
- Completes deep linking experience in certain apps.

UTM behavior

Note
This is enabled by default. To disable this functionality, go to Link Settings > Advance Settings > Analytics mapping with UTM.

When redirecting to a web URL, Branch automatically passes through any values from the following Branch link analytics tags as UTM parameters:
- ~campaign -> utm_campaign
- ~channel -> utm_source
- ~feature -> utm_medium
This applies to web URLs defined using any of the following $fallback_url, $ios_url, $android_url, $desktop_url, $original_url, and $canonical_url.
If these UTM parameters are already detected on the URLs being redirected to, Branch will not overwrite them.
For more information about UTM parameters, please read Google Analytic's Custom Campaigns article.

Expiration behavior

The default expiration behavior will vary depending on the type of Branch Link you're using.

Link Type	Expiration
Short Links	Starting March 11, 2024. Expires 380 Days after creation. This expiration window is reset when the Short Link is clicked or if Branch receives a read request via the Deep Linking API.
Long Links	Does not expire
Quick Links	Does not expire
Ad Links	Does not expire

Configure deep links

You can add any of your own key-value parameters to a Branch link. These parameters will be passed to your app via the Branch SDK, however some keys will have specific extra effects.

Link data

Specify where to deep link users into the app, or configure advanced settings like device-based targeting, attribution windows, and custom keys specific to your app.

Name	Key	Definition
Default Deep Link Path	`$deeplink_path`	Sets a default deep link path for all platforms. When a user opens a Branch Link with this parameter, the Branch SDK will route them to the specified in-app content path.
iOS Deep Link Path	`$ios_deeplink_path`	Sets the deep link path for iOS apps, which overrides the default path. When a user on an iOS device opens a Branch Link, the Branch SDK will route them to the specified in-app content path.
Android Deep Link Path	`$android_deeplink_path`	Sets the deep link path for Android apps. When the Branch SDK receives a link with this parameter set, it will automatically load the custom Android URI path contained within.
Default Fallback URL	`$fallback_url`	Change the redirect destination for all platforms so you don’t have to enable it by platform. Branch will forward all robots to this URL, which overrides any OG tags entered in the link. System-wide default URL (set in Link Settings).
Original Web URL	`$canonical_url`	The corresponding web URL for the in-app content.
Unique Content Identifier	`$canonical_identifier`	This is the unique identifier for content that will help Branch dedupe across many instances of the same thing. Suitable options include a website with pathing, or a database with identifiers for entities.
iOS Passive Deepview Template	`$ios_passive_deepview`	The name of the template to use for iOS.
Android Passive Deepview Template	`$android_passive_deepview`	The name of the template to use for Android.
Always Deep Link to App	`$always_deeplink`	Set to false to make links always fall back to your mobile site. Does not apply to Universal Links or Android App Links.
Deep Linking Window (Seconds)	`$match_duration`	Lets you control the snapshotting match timeout (the time that a click will wait for an app open to match), also known as attribution window. Specified in seconds.
Default URI Redirect Mode	`$uri_redirect_mode`	Allows you to control how and when Branch uses URI schemes to open your app.
iOS URI Redirect Mode	`$ios_uri_redirect_mode`	Allows you to control how and when Branch uses URI schemes to open your app on iOS.
Android URI Redirect Mode	`$android_uri_redirect_mode`	Allows you to control how and when Branch uses URI schemes to open your app on Android.

Deep linking parameters

Set the specific in-app content a user is routed to.

Name	Key	Definition
Default Deep Link Path	`$deeplink_path`	Sets a default deep link path for all platforms. When a user opens a Branch Link with this parameter, the Branch SDK will route them to the specified in-app content path.
iOS Deep Link Path	`$ios_deeplink_path`	Sets the deep link path for iOS apps, which overrides the default path. When a user on an iOS device opens a Branch Link, the Branch SDK will route them to the specified in-app content path.
Android Deep Link Path	`$android_deeplink_path`	Sets the deep link path for Android apps. When the Branch SDK receives a link with this parameter set, it will automatically load the custom Android URI path contained within.
Desktop Deep Link Path	`$desktop_deeplink_path`	Sets the deep link path for desktop apps. You must fetch this parameter from the link to route the user to the correct destination.

Link behavior and redirects

Set where to send users if the app cannot be opened (for example, if it is not installed).

Note
Using redirect parameters on Branch Links requires a valid credit card to be entered on your account. Alternatively, you can set up an Enterprise account.

Expand to view information about forced redirects

Forced Redirections

Prevent error messages from other apps when Branch deep links are clicked.

Key	Value	Usage
`$uri_redirect_mode`	0	Conservative mode. We don't try to open the app if the user can see an error.
`$uri_redirect_mode`	1	Smart redirect mode. This is the default value that yields the same behavior as 0 until we know the user has the app installed through Branch persona data. In that case, force URI schemes to open the app.
`$uri_redirect_mode`	2	Forceful redirect mode. Always try to force open the app, even if it risks showing an error message when the app is not installed.

Forced redirections will not force open the app when the link is configured with an "Active Deepview" or "NativeLink" since they are intended to load a webpage and not redirect elsewhere.
OS level redirect modes can be enabled by utilizing the parameters $ios_uri_redirect_mode and $android_uri_redirect_mode.
Supported Apps
- Facebook newsfeed iOS
- Instagram iOS
- Twitter iOS
- Safari iOS
- Firefox iOS & Android

Name	Key	Definition
Default Fallback URL	`$fallback_url`	Sets a single fallback URL for all platforms where users are redirected if the app cannot be opened or if they do not have the app downloaded. If the link is a web-only link, this will be the destination. Note: Branch forwards all web crawlers (robots) to this URL, which overrides any Open Graph (OG) tags you set.
iPad Redirect URL	`$ipad_url`	Sets a specific redirect URL for iPad users, overriding the `$ios_url` value.
Samsung Galaxy Store Redirect URL	`$samsung_url`	Redirect users on Samsung devices to the Samsung Galaxy Store. You must provide the link in the following format: `http://www.samsungapps.com/appquery/appDetail.as?appId=YOUR.PACKAGE.NAME`
Huawei App Gallery URL	`$huawei_url`	Redirect users on Huawei devices to the Huawei AppGallery. The URL format must following Huawei’s App Linking guide.
Force Web Open	`$web_only`	Forces the link to open the web URL set in `$fallback_url` instead of opening the app.
Mobile Web Only (Desktop App)	`$mobile_web_only`	When set to `true`, the link will open your website on mobile devices but will open the app on desktop.
Desktop Web Only (Mobile App)	`$desktop_web_only`	When set to `true`, the link will open your website on desktop but will open the app on mobile devices.
Always Deep Link to App	`$always_deeplink`	Set to `false` to make links always fall back to your mobile site. Does not apply to Universal Links or Android App Links.
Enable iOS NativeLink	`$ios_nativelink`	When set to true, the link routes through NativeLink to enable deferred deep linking for iOS 15+ and Private Relay users.
Default URI Redirect Mode	`$uri_redirect_mode`	Allows you to control how and when Branch uses URI schemes to open your app.
iOS URI Redirect Mode	`$ios_uri_redirect_mode`	Allows you to control how and when Branch uses URI schemes to open your app on iOS.
Android URI Redirect Mode	`$android_uri_redirect_mode`	Allows you to control how and when Branch uses URI schemes to open your app on Android.
iOS App Store Redirect Delay (Milliseconds)	`$ios_redirect_timeout`	Control the timeout that the client-side JS waits after trying to open up the app before redirecting to the App Store. Specified in milliseconds.
Android Play Store Redirect Delay (Milliseconds)	`$android_redirect_timeout`	Control the timeout that the client-side JS waits after trying to open up the app before redirecting to the Play Store. Specified in milliseconds.

Attribution and analytics control

Control the time window during which installs, opens, or conversions can be attributed to a link click or impression.

Name	Key	Definition
Click-to-Install Window (Days)	`$click_install_window_days`	Time between a click and an install or reinstall. For example: `.../?$click_install_window_days=3`
Click-to-Open/Session Window (Days)	`$click_session_start_window_days`	Time between a click and an open or web session start. For example: `.../?$click_session_start_window_days=7`
Click-to-Conversion Window (Days)	`$click_conversion_window_days`	Time between a click and a conversion event. Conversion events include commerce events, all custom events, and all view events. For example: `.../?$click_conversion_window_days=30`
Impression-to-Install Window (Days)	`$impression_install_window_days`	Time between an ad impression and an install and reinstall. For example: `.../?$impression_install_window_days=3`
Impression-to-Open/Session Window (Days)	`$impression_session_start_window_days`	Time between an ad impression and an open or web session start. For example: `.../?$impression_session_start_window_days=1`
Impression-to-Conversion Window (Days)	`$impression_conversion_window_days`	Time between an ad impression and a conversion event. Conversion events include commerce events, all custom events, and all view events. For example: `.../?$impression_conversion_window_days=7`
Deep Linking Window (Seconds)	`$match_duration`	Lets you control the snapshotting match timeout (the time that a click will wait for an app open to match), also known as attribution window. Specified in seconds.
Deep Link Only (No Attribution)	`$deeplink_no_attribution`	Set to true for the links to only support deep linking without any attribution for that link. Note: Using this will lose all link metrics when set to `true`.
Disable Click Tracking & Analytics	`$do_not_process`	This will prevent click tracking and storage of link analytics. Deep link data will still flow into the app from link click to app open.

Analytical data keys

These labels allow you to filter and organize your deep links. Refer to the “Reserved prefixes” section of this article to learn more about the ~ prefix.

Key	Usage
`~channel or channel`	Use channel to tag the route that your link reaches users. For example, tag links with `'Facebook'` or `'LinkedIn'` to help track clicks and installs through those paths separately
`~feature or feature`	This is the feature of your app that the link might be associated with. For example, if you had built a referral program, you would label links with the feature 'referral'
`~campaign or campaign`	Use this field to organize the links by actual campaign. For example, if you launched a new feature or product and want to run a campaign around that
`~campaign_id`	Use this field to organize the links by actual campaign id. For example, if you launched a new feature or product and want to run a campaign around that
`~customer_campaign`	The customer campaign specified for the last attributed touch. can be specified on links by the client.
`~stage`	Use this to categorize the progress or category of a user when the link was generated. For example, if you had an invite system accessible on level 1, level 3 and 5, you could differentiate links generated at each level with this parameter
`~tags or tags`	This is a free form entry with unlimited values `['string']`. Use it to organize your link data with labels that don't fit within the bounds of the above
`~secondary_publisher`	secondary publisher specified for the last attributed touch. passed by the ad network.
`~customer_secondary_publisher`	The ID of the secondary publisher specified for the last attributed touch. can be specified on links by the client.
`~creative_name`	The creative name specified for the last attributed touch.
`~creative_id`	The creative ID specified for the last attributed touch.
`~ad_set_name`	The ad set name specified for the last attributed touch.
`~ad_set_id`	The ad set ID specified for the last attributed touch.
`~customer_ad_set_name`	The customer ad set name specified for the last attributed touch. can be specified on links by the client.
`~ad_name`	The ad name specified for the last attributed touch.
`~ad_id`	The ad ID specified for the last attributed touch.
`~customer_ad_name`	The customer ad name specified for the last attributed touch. can be specified on the link by the client.
`~keyword`	The keyword specified for the last attributed touch.
`~keyword_id`	The unique ID for keyword of the last touch
`~customer_keyword`	The customer keyword of the last touch. Can be specified on links by the client.
`~placement`	The placement of the last touch, as set with an analytics tag. Actual app or website the ad appears on display campaigns.
`~placement_id`	The ID of placement of the last touch, as set with an analytics tag. Actual app or website the ad appears on display campaigns.
`~customer_placement`	The customer specified placement of the last touch, as set with an analytics tag. Actual app or website the ad appears on display campaigns. Can be specified on the link by the client.
`~sub_site_name`	Reference to the site where the ad was displayed.
`~customer_sub_site_name`	Customer reference to the site where the ad was displayed. Can be specified on links by the client.

Social media previews

Customize how a link preview appears when shared on social media platforms.

Name	Key	Definition
Social Media Image Width	`$og_image_width`	Set the image’s width in pixels for social media previews.
Social Media Image Height	`$og_image_height`	Set the image’s heigh in pixels for social media previews.
Social Media Video URL	`$og_video`	Set a video as it will be seen in social media previews.
Social Media Base URL	`$og_url`	Set the base URL of the link as it will be seen in social media previews.
Social Media Card Type	`$og_type`	Set the type of custom card format link as it will be seen in social media previews. Don’t set this property when sharing deep links on Facebook.
Advanced Social Media Redirect	`$og_redirect`	Advanced, not recommended for most use cases. Set a custom URL that we redirect social media bots to in order to retrieve all the appropriate tags.
Twitter (X) Card Type	`$twitter_card`	Set the Twitter card type of the link (for example, player). You must allowlist your deep link with the Twitter Card Validator.
Twitter (X) Site Name	`$twitter_site`	Set the site for Twitter (X).
Twitter (X) App Country	`$twitter_app_country`	Set the app country for the app card.
Twitter (X) Video Player URL	`$twitter_player`	Set the video player’s URL. Default to the video value of `$og_video`.
Twitter (X) Player Width	`$twitter_player_width`	Set the player’s width in pixels.
Twitter (X) Player Height	`$twitter_player_height`	Set the player’s height in pixels.
Custom Social Media Meta Tags	`$custom_meta_tags`	Valid string JSON dictionary of the tags’ keys and values. For example: `{"twitter:player:stream": "https://branch.io"}`

Content metadata

Set the content the link points to, helping with organization, deduplication, and search indexing.

Name	Key	Definition
Unique Content Identifier	`$canonical_identifier`	This is the unique identifier for content that will help Branch dedupe across many instances of the same thing. Suitable options include a website with pathing, or a database with identifiers for entitie
Original Web URL	`$canonical_url`	The corresponding web URL for the in-app content
Publicly Indexable	`$publicly_indexable`	Cannot modify here. Must be set by the Branch Universal Object.
Content Type Label	`$content_type`	This is a label for the type of content present. Apple recommends that you use uniform-type identifier as described here.
Content Expiration Date	`$exp_date`	Expiry date for the content and any associated link data. Represented as UTC epoch millisecond.

Deepview templates

Templates for Deepviews on iOS and Android.

Name	Key	Definition
iOS Passive Deepview Template	`$ios_passive_deepview`	The name of the Deepview template to use for iOS.
Android Passive Deepview Template	`$android_passive_deepview`	The name of the Deepview template to use for Android.

Custom data

Create custom keys to pass any custom data to be read inside your app. For example:

Custom key (example)	Custom value (example)	Custom usage (example)
random	123	Sending random information to your app.

Link appearance

Customize the appearance of your Branch Short Link.

Key	Default	Usage
`alias`	none	Specify a link alias to replace of the standard encoded short URL (e.g. `https://example.app.link/aQXXDHaxKF` -> `https://example.app.link/october-campaign` or `https://example.app.link/product/id1234`). Link aliases must be unique per app (a `400 error` will occur if you create an alias already taken). Also note that we don't currently support single character path segments after the domain (`/a/`, `/b/`, `/c/`, etc).

Other reserved keys

Key	Usage
`access_token` or `AccessToken`	Used by Branch to determine if a deep link is a valid Branch link or not.
`auth_token`or `AuthToken`	Used by Branch to determine if a deep link is a valid Branch link or not.
`data`	Used by Branch to contain top-level link information. If this parameter is added to a Branch link via appending query params, it will be dropped. It can be safely used when creating a link manually via the dashboard.
`password`	If this parameter is added to a Branch link via appending query params, it will be dropped.
`auth`	If this parameter is added to a Branch link via appending query params, it will be dropped.

Reserved prefixes

Branch adds prefixes to each deep link data key to explain the key. You will see this added to the beginning of the different types of keys below.

Prefix	Usage
`$`	Branch reserved keyword.
`~`	Branch analytical data.
`+`	Branch added values.

Read deep links

Deep link data gets sent from your link to your app integration.

Data structure

Example deep link data structure:

{
          "randomized_bundle_token": "427469360685348303",
          "link": "https://example.app.link?%24randomized_bundle_token=427469360685348303",
          "session_id": "429691081177874743",
          "data": {
            "$canonical_identifier": "item/1503684554354.28",
            "$canonical_url": "https://example.com/home?utm_campaign=test&deeplink=value",
            "$desktop_url": "http://example.com/home",
            "$randomized_bundle_token": "427469360685348303",
            "$og_description": "My Content Description",
            "$og_image_url": "http://lorempixel.com/200/200/",
            "$og_title": "46D6D28E-0390-40E4-A856-BD74F34D24C8",
            "$publicly_indexable": 1,
            "+click_timestamp": 1503684563,
            "+clicked_branch_link": true,
            "+is_first_session": false,
            "+match_guaranteed": true,
            "custom": "blue",
            "random": "FE848A5B-78F7-42EC-A253-9F795FE91692",
            "added": "1503684554354.33",
            "~campaign": "new launch",
            "~channel": "facebook",
            "~creation_source": 3,
            "~feature": "sharing",
            "~id": 429691043152332059,
            "~referring_link": "https://example.app.link/X7OsnWv9TF",
            "~stage": "new person",
            "~tags": [
              "one",
              "two"
            ]
          }
        }

Callback values

Additional properties read from the initSession within your app and website integrations.

Key	Usage
`~id`	Automatically generated 18 digit ID number for the link that drove the install/open, if present (0 for dynamic and 3P links).
`~referring_link`	The referring link that drove the install/open, if present.
`~creation_source`	Where the link was created (`0` API , `1` Quick Link, `2` SDK, `3` iOS SDK , `4` Android SDK , `5` Web SDK, `6` Dynamic, `7` Third party).
`+match_guaranteed`	If the match was made with 100% accuracy.
`+referrer`	The referrer for the link click, if a link was clicked.
`+is_first_session`	`true` if first session (install), `false` if any other session (open) or if it did not previously exist in the Branch Link Graph. Default is `false`.
`+clicked_branch_link`	Whether or not the user clicked a Branch link that triggered this session. Default is `false`.
`+non_branch_link`	App was opened from a non Branch link (third party, invalid Branch deep link, or Branch key mismatch).