Overview

You can use Deep Links on your Journeys, Ads links, Quick Links, and Email. In this guide, we will walk you through how to configure your default and custom link behavior, as well as how to create short and long links.

Default Link Behavior

If Your App Is Not Installed

• User clicks on a Branch deep link

• Device navigates to the fallback (e.g. an app store or website)

  • App Stores Supported:
    • 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 App Is 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

Expected Link Behavior

Mobile

• Expected link behavior is dependent on whether or not the app supports deep linking

• *Able to force app open using $uri_redirect_mode or enabling a Deepview

Desktop

• Expected link behavior is dependent on whether or not the app supports deep linking

• By default, we attempt to launch the apps via URI schemes and load the desktop redirect fallback in the background

• *Only launches background desktop web fallbacks using $afterclick_desktop_url

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

• Your app is not installed
  • Device navigates to the fallback (e.g. an app store or website)
• 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' (docs)
• 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 Deep Views to display content as a website
  • Increases install attribution
  • Completes deep linking experience in certain apps

UTM Behavior

❗️

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.

Create Deep Links

Short Links

• Short links are the most common deep links created via the Branch SDK or Deep Linking API.
• You can customize the subdomain of example.app.link, or change to your own personal domain (links.yoursite.com)
• You can tailor the appearance of the shortcode to a custom alias during creation
  • Aliases can be short strings, e.g. https://example.app.link/october-sale
  • Or can be a full link path, e.g. https://example.app.link/product/id1234
• Short links encapsulate link data inside them on link creation
  • e.g. existing link https://example.app.link/fzmLEhobLD
• Short links can have additional data appended to them
  • e.g. dynamic link https://example.app.link/fzmLEhobLD?content_id=123
• Methods of creating short links
  • Use Quick Links for fast link creation and easy tracking
  • Use our App SDK to create and share links within your app
  • Use our Web SDK to create links that help convert your web users to app users
  • Use our HTTP API to programmatically create links from your server
  • Use our Chrome Extension to generate links from your browser

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.
  • e.g. existing link https://example.app.link/fzmLEhobLD?foo=bar&baz=456&$fallback_url=https%3A%2F%2Fbranch.io%2F
  • e.g. dynamic link 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 link domain
  • e.g. existing link https://link.example.com/5NPh/p4M09KRLrD?foo=bar&baz=456&$fallback_url=https%3A%2F%2Fbranch.io%2F
  • e.g. dynamic link https://link.example.com/a/key_live_kaFuWw8WvY7yn1d9yYiP8gokwqjV0Swt?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 bnc.lt
  • e.g. existing link https://bnc.lt/5NPh/p4M09KRLrD?foo=bar&baz=456&$fallback_url=https%3A%2F%2Fbranch.io%2F
  • e.g. dynamic link https://bnc.lt/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
  • e.g. https://example.app.link/?foo=bar&~tags=tag1&~tags=tag2

Configure Deep Links

You're free to 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.

Reserved Prefixes

Branch adds additional properties to your deep link data to explain the link.

Keys for Reporting Analytics

These labels allow you to filter and organize your deep links.

These labels allow you to customize attribution windows for a single link.

Custom Data

Pass any custom data to be read inside your app.

Redirections

Navigate to different locations based on device information. Navigation URLs must be websites, not Deep Links.

Note: Usage of redirection parameters on Branch Links requires a credit card on your account or set up an Enterprise account.

Forced Redirections

Prevent error messages from other apps when Branch Deep Links are clicked.

• 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

Deep Linking

Navigate to different locations based on device information.

Content

Handle content properties.

Deepview

Enable / control active deepview properties.

Control passive deepview templates.

Link Appearance

Customize the appearance of your Branch Short Link.

Open Graph

The keys in the table below are used to handle Facebook properties.

Please note the following defaults Branch maintains for meta tags:

• Branch Links created through the Dashboard will scrape the original web URL for meta tags.
• Branch Links created via one of our APIs will scrape $original_url, $fallback_url, and $desktop_url for meta tags, in that order.

Twitter

Handle Twitter properties.

Other Reserved Keys

Custom Tags

• Handle custom meta tags

• Valid dictionary example: "{"twitter:player:stream": "https://branch.io"}". This will result in the following meta tag: <meta property="twitter:player:stream" content="https://branch.io" />
• If you create the link via the Dashboard, don’t worry about stringifying the dictionary. It will be done automatically.
• apple_touch_icon is a special key in the dictionary. If you set it, we will add a <link rel="apple-touch-icon" href="<url>" /> tag to the scraped HTML page. This will allow you to show a custom icon for previews in iMessage, Safari Bookmarks, Slack, etc.

Universal Object

📘

Branch Universal Object

The Branch Universal Object are fundamental to tracking and logging events with Branch. To learn more, view our full guide here.

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