Appearance

Get Help

Deep Linking Full Reference

Overview ​

You can use deep links for your Journeys, Ads Links, Short 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.

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

Short Links are the most common deep links created with 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 also 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).

Check out our Create Web Links and Create App Links articles to learn more about creating Short 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

Use the Link Validator to view the expected and actual behavior of your 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.

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

The most popular and commonly used data options.

NameDefault valueKeyDefinition
Deep Link Pathopen?link_click_id=1234$deeplink_pathSets 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_pathSets 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_pathSets 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.
Fallback URL$fallback_urlChange 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).
Canonical URL$canonical_urlThe corresponding web URL for the in-app content.
Unique Content Identifier$canonical_identifierThis 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 Templatebranch_default$ios_passive_deepviewThe name of the Deepview template that your link will fall back to for iOS.
Android Passive Deepview Templatebranch_default$android_passive_deepviewThe name of the Deepview template that your link will fall back to for Android.
Always Deep Link to Apptrue$always_deeplinkSet 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)7200$match_durationLets 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.
URI Redirect Mode$uri_redirect_modeAllows you to control how and when Branch uses URI schemes to open your app.
iOS URI Redirect Mode$ios_uri_redirect_modeAllows you to control how and when Branch uses URI schemes to open your app on iOS.
Android URI Redirect Mode$android_uri_redirect_modeAllows 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.

NameDefault valueKeyDefinition
Deep Link Pathopen?link_click_id=1234$deeplink_pathSets 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_pathSets 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_pathSets 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_pathSets the deep link path for desktop apps. You must fetch this parameter from the link to route the user to the correct destination.

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.

KeyValueUsage
$uri_redirect_mode0Conservative mode. We don't try to open the app if the user can see an error.
$uri_redirect_mode1Smart 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_mode2Forceful 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
NameKeyDefinition
Fallback URL$fallback_urlSets 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.
Country-Specific Fallback URL$fallback_url_xxChange the redirect endpoint for all platforms based on a lower-case Alpha-2 country code. For example, $fallback_url_de="..." would redirect Germany deep link clicks. You should also set $fallback_url to act as the global redirect in addition to the country-specific ones. Warning: If platform-specific redirects (like $ios_url or $desktop_url) are set, they will override the country-specific redirect. We recommend you only use $fallback_url_xx for the country-specific redirects and $fallback_url to catch all other users.
iPad Redirect URL$ipad_urlSets a specific redirect URL for iPad users, overriding the $ios_url value.
Samsung Galaxy Store Redirect URL$samsung_urlRedirect 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_urlRedirect users on Huawei devices to the Huawei AppGallery. The URL format must follow Huawei’s App Linking guide.
Force Web Open$web_onlyForces the link to open the web URL set in $fallback_url instead of opening the app.
Mobile Web Only (Desktop App)$mobile_web_onlyWhen 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_onlyWhen 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_deeplinkSet 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_nativelinkWhen set to true, the link routes through NativeLink to enable deferred deep linking for iOS 15+ and Private Relay users.
URI Redirect Mode$uri_redirect_modeAllows you to control how and when Branch uses URI schemes to open your app.
iOS URI Redirect Mode$ios_uri_redirect_modeAllows you to control how and when Branch uses URI schemes to open your app on iOS.
Android URI Redirect Mode$android_uri_redirect_modeAllows you to control how and when Branch uses URI schemes to open your app on Android.
iOS App Store Redirect Delay (Milliseconds)$ios_redirect_timeoutControl 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_timeoutControl 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.

NameKeyDefinition
Click-to-Install Window (Days)$click_install_window_daysTime 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_daysTime 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_daysTime 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_daysTime 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_daysTime 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_daysTime 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_durationLets 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_attributionSet 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_processThis 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.

KeyUsage
~channel or channelUse 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 featureThis 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 campaignUse 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_idUse 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_campaignThe customer campaign specified for the last attributed touch. Can be specified on links by the client.
~stageUse 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 tagsThis 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_publisherSecondary publisher specified for the last attributed touch. Passed by the ad network.
~customer_secondary_publisherThe ID of the secondary publisher specified for the last attributed touch. Can be specified on links by the client.
~creative_nameThe creative name specified for the last attributed touch.
~creative_idThe creative ID specified for the last attributed touch.
~ad_set_nameThe ad set name specified for the last attributed touch.
~ad_set_idThe ad set ID specified for the last attributed touch.
~customer_ad_set_nameThe customer ad set name specified for the last attributed touch. Can be specified on links by the client.
~ad_nameThe ad name specified for the last attributed touch.
~ad_idThe ad ID specified for the last attributed touch.
~customer_ad_nameThe customer ad name specified for the last attributed touch. Can be specified on the link by the client.
~keywordThe keyword specified for the last attributed touch.
~keyword_idThe unique ID for keyword of the last touch.
~customer_keywordThe customer keyword of the last touch. Can be specified on links by the client.
~placementThe placement of the last touch, as set with an analytics tag. Actual app or website the ad appears on display campaigns.
~placement_idThe ID of placement of the last touch, as set with an analytics tag. Actual app or website the ad appears on display campaigns.
~customer_placementThe 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_nameReference to the site where the ad was displayed.
~customer_sub_site_nameCustomer 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.

NameKeyDefinition
Social Media Image Width$og_image_widthSet the image’s width in pixels for social media previews.
Social Media Image Height$og_image_heightSet the image’s height in pixels for social media previews.
Social Media Video URL$og_videoSet a video as it will be seen in social media previews.
Social Media Base URL$og_urlSet the base URL of the link as it will be seen in social media previews.
Social Media Card Type$og_typeSet 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.
Social Media App ID$og_app_idSet the app ID tag.
Advanced Social Media Redirect$og_redirectAdvanced, 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_cardSet 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_siteSet the site for Twitter (X).
Twitter (X) App Country$twitter_app_countrySet the app country for the app card.
Twitter (X) Video Player URL$twitter_playerSet the video player’s URL. Default to the video value of $og_video.
Twitter (X) Player Width$twitter_player_widthSet the player’s width in pixels.
Twitter (X) Player Height$twitter_player_heightSet the player’s height in pixels.
Custom Social Media Meta Tags$custom_meta_tagsValid 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.

NameKeyDefinition
Unique Content Identifier$canonical_identifierThis 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.
Canonical URL$canonical_urlThe corresponding web URL for the in-app content.
Publicly Indexable$publicly_indexableCannot modify here. Must be set by the Branch Universal Object.
Content Type Label$content_typeThis is a label for the type of content present. Apple recommends that you use uniform-type identifier as described here.
Content Expiration Date$exp_dateExpiry date for the content and any associated link data. Represented as UTC epoch millisecond.

Deepview templates ​

Templates for Deepviews on iOS and Android.

NameKeyDefinition
iOS Passive Deepview Template$ios_passive_deepviewThe name of the Deepview template to use for iOS.
Android Passive Deepview Template$android_passive_deepviewThe 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)
random123Sending random information to your app.

Customize the appearance of your Branch Short Link.

KeyDefaultUsage
aliasnoneSpecify a link alias to replace 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 ​

KeyUsage
access_token or AccessTokenUsed by Branch to determine if a deep link is a valid Branch link or not.
auth_token or AuthTokenUsed by Branch to determine if a deep link is a valid Branch link or not.
dataUsed 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.
passwordIf this parameter is added to a Branch link via appending query params, it will be dropped.
authIf 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.

PrefixUsage
$Branch reserved keyword.
~Branch analytical data.
+Branch added values.

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

Data structure ​

Example deep link data structure:

json
{
  "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.

KeyUsage
~idAutomatically generated 18 digit ID number for the link that drove the install/open, if present (0 for dynamic and 3P links).
~referring_linkThe referring link that drove the install/open, if present.
~creation_sourceWhere the link was created (0 API, 1 Short Link, 2 SDK, 3 iOS SDK, 4 Android SDK, 5 Web SDK, 6 Dynamic, 7 Third party).
+match_guaranteedIf the match was made with 100% accuracy.
+referrerThe referrer for the link click, if a link was clicked.
+is_first_sessiontrue 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_linkWhether or not the user clicked a Branch link that triggered this session.

Default is false.
+non_branch_linkApp was opened from a non Branch link (third party, invalid Branch deep link, or Branch key mismatch).

FAQs ​

Does a Branch-generated QR code have an expiration date?

No, QR codes do not have an expiration date. The QR code has a Short Link behind it. As long as the Short Link is active, the QR code will continue to work. Short Links will always be active if not deleted or archived. However, if you change the link domain (yourapp.app.link) of your Branch app, all Short Links and the QR codes created with the old domain will stop working.

Are the number of 'Opens' included in the number of 'Installs' reported in Branch?

Opens are not included in installs. If a user who already has the app clicks on the link and opens the app, it is counted as an open. If the app is not installed, the user is taken to the app/play store to install the app. The first time they open the app after the install is counted as an install.

Can updating the Social Media Descriptors affect an app’s ranking in app store searches?

Updating the Social Media descriptors will only change the Image and description associated with the link, will not have any impact on the app's search ranking.

These values will be updated next time the link is scraped by the respective platform.

How long does it take for new images to appear on social media preview once updated?

Branch will update the link 'og' parameters immediately after it is updated. However how the social media descriptors show up on a platform are controlled by the platform. Different platforms handle these links in different ways, the platform might scrape the link every time it is shared and the image might get refreshed immediately. However in most cases the link is not scraped regularly hence you might see a time lag before the image is updated for the link. If you are sharing on Facebook owned platforms you can manually scrape the link by visiting https://developers.facebook.com/tools/debug/.

Please note that the $og_image_url social preview feature is reserved for paid Branch accounts with a dedicated contract. If you do not have a paid Branch account, you will not see this feature in Branch.

How do I fix the following error: “URL doesn’t pass security test”?

The error message, “URL doesn’t pass security tests,” can show up when the link that you are trying to use as a redirection URL does not match the redirection allowlist set for your app. For example, Branch can create custom allowlists where links created for your app can only redirect to *.example.com.

If you try to create a link that redirects to any other domain other than *.example.com, you will see this error message and the link will not be created.

You can update your redirection allowlist in Branch. Read our Advanced Link Configuration article to learn how.

© 2026 BranchPrivacyTermsCookie Policy