Branch

This integration is maintained by Branch. Please contact Branch for support.

Branch is a mobile measurement and deep linking platform that helps you create seamless experiences and engage users in your app. By making small changes to your Airship implementation, you can use Branch deep links in your Airship mobile messages and emails.

You can also use Branch’s attribution events to understand your users in Airship. Use this data to automatically message users at critical points in your audience’s lifecycle to increase conversions and customer satisfaction.

Mobile Deep Linking with Branch

Deep linking makes your app more responsive and capable of navigating to arbitrary content in response to push notifications or other interactions, much in the same way that URLs can link you to specific pages on the Web. If you have added Branch deep links to your app, you can use those with Airship by making a small change to your Airship SDK implementation. The following examples demonstrate how to hand off deep links from Airship to the Branch SDK.

Using the iOS Deep Linking Delegate

With the Airship iOS SDK, you will register a delegate with the SDK that implements the DeepLinkDelegate protocol.

UAirship.shared.deepLinkDelegate = myDeepLinkDelegate

After you’ve created and registered your deep link delegate, implement the receivedDeepLink:completionHandler: callback. This will be called when a deep link has been triggered from Airship with a provided URL, making the delegate responsible for processing the provided URL.

The final step is to hand off the URL to the Branch SDK.

func receivedDeepLink(_ url: URL, completionHandler: @escaping () -> ()) {
    if (Branch.getInstance()?.handleDeepLink(withNewSession: url) == true) {
        completionHandler()
        return
    }
    
    ...
}

With the Airship Android SDK, you can customize how deep links are handled by setting a DeepLinkListener on the UAirship instance. This will be called when a deep link has been triggered from Airship. If your app is using deep links through Android implicit intents, you will then launch your appropriate Branch activity.

@Override
public void onAirshipReady(@NonNull UAirship airship) {
   airship.setDeepLinkListener(deepLink -> {
        /* Handle the deepLink
        https://help.branch.io/developers-hub/docs/android-advanced-features#section-handle-links-in-your-own-app  */

        Intent intent = new Intent(this, YourActivity.class);
        intent.putExtra("branch",target);
        intent.putExtra("branch_force_new_session",true);
        
        return true;
   });

   ...
}

Email Deep Linking with Branch

You can use Branch to support deep links from emails to your app or other content. Branch handles deep links intelligently, so that your links open in your app when possible, but will resolve to a web browser if your users open links on a desktop computer or do not have your app installed.

 Note

A working click tracking domain is a prerequisite for this integration. Please contact Airship support if you do not know your domain address or have not yet set one up.

When you enable deep link support through Branch, Branch wraps links in your emails inside a tracking URL. The Branch SDK resolves this URL and determines whether or not a client has your app, directing users to the appropriate content in the app or their web browser.

In the Branch dashboard, navigate to Email »» Manager »» Airship and follow the Universal Email Integration Guide. Continue on to configure Airship.

  1. Enter your click tracking domain in the provided field.
  2. Enter https://spgo.io as the Airship domain.
  3. Click Save.

Configure DNS Records

Point your DNS CNAME to Branch’s thirdparty.bnc.lt domain. See this Branch email integration help article for details.

 Note

You must have a CNAME entry for your tracking domain that points to a specific Branch URL, e.g.: branch-tracking-airship.com.

Branch will verify DNS records and confirm the configuration was successful.

Branch Attribution Data in Airship

Branch’s People-Based Attribution events connect individual users’ actions across platforms, helping you better understand your users and their cross-platform behaviors.

This integration gives you the power to set up AutomationA set of conditions that your audience must meet before they receive a message. rules and SequencesA series of messages that is initiated by a trigger. Airship sends messages in the series based on your timing settings, and you can also set conditions that determine its continuation. Sequences can be connected to each other and to other messaging components to create continuous user experiences in a Journey. based on attribution events from Branch.

sequenceDiagram participant A as Audience participant B as Branch participant C as Airship B->>A: Identify user by Airship channel_id A->>B: User performs attribution event B->>C: Forward attribution event as custom event C->>A: Message to channel_id in response to custom event

Events from Branch are associated with channel_id values in Airship.

Before you can take advantage of this integration, you must update your Branch implementation to get the Airship channel_id and set it as a request’s metadata in Branch before sending events. This makes sure that events tracked by Branch are associated with appropriate users in Airship.

For more information, see:

Enabling the Branch Attribution Data Integration

Before you enable your integration, make sure that you have:

  • Integrated with both the Airship and Branch SDKs.
  • Updated your Branch implementation to set users’ identities as their channel_id from Airship.
  1. In Airship, create a bearer token with the All Access role. This token will authorize Branch to send custom events into Airship.
    1. Go to Settings » Project Configuration and click Manage for Tokens.
    2. Click Create Token.
    3. Enter a token Name. This is just a friendly name to help you recognize your tokens in Airship.
    4. Select the Role you want to grant for this token. For additional information, see Airship API Security.
      • Audience Modification: Grants read and write permission to audience APIs, including channels, named users, segments, lists, etc. Use this permission for users sending custom events into Airship.
      • All Access: Grants full access to your Airship project, except Acoustic integrations. You should use this permission when creating a token for an inbound message handling webhook.
    5. Click Create Token.
    6. Copy the values, then click Got it to close the window.
  2. In Branch, go to Data Integration.

  3. Under Data Integration Partner, click Airship.

  4. Enter your Airship App Key and the Bearer Token you created in earlier steps.

  5. Click Enable.

Taking Advantage of Custom Events

You can set up AutomationA set of conditions that your audience must meet before they receive a message. rules or SequencesA series of messages that is initiated by a trigger. Airship sends messages in the series based on your timing settings, and you can also set conditions that determine its continuation. Sequences can be connected to each other and to other messaging components to create continuous user experiences in a Journey. to send your audience messages when Airship receives custom events — or specific values in custom events — from Branch.

You can even reference event properties in an automation or sequence using HandlebarsHandlebars is Airship’s templating language for personalization. Handlebars expressions use double curly braces wrapped around a content template, ranging from a simple variable, e.g., {{first_name}} to complex evaluations of personalization data. . Using event properties to personalize or modify your message for each member of your audience can help increase the relevance of your message and the likelihood that your audience will engage.

For example, to personalize a message using the custom purchase event from Branch below, you would probably set up your message to iterate over certain products in the contentItems array, and provide total purchase information from the items object.

Example message:
Thank you for your purchase!
{{#each contentItems}}
{{$quantity}} x {{$product_brand}} {{$product_name}} = {{$price}}{{$currency}}
{{/each}}

Example Branch purchase event:
{
    "id": "aae70da5-a276-4dd4-a11e-f5b5796a52f1",
    "offset": "1000000000780",
    "occurred": "2020-04-24T22:37:53.000Z",
    "processed": "2020-04-24T22:40:35.337Z",
    "device": {
        "ios_channel": "c014a2ed-4c30-4f6d-a9b3-e2ba7a01b45c",
        "channel": "c014a2ed-4c30-4f6d-a9b3-e2ba7a01b45c",
        "device_type": "IOS",
        "attributes": {
            "locale_variant": "",
            "app_version": "1.0",
            "device_model": "x86_64",
            "connection_type": "WIFI",
            "app_package_name": "com.urbanairship.partner.branch",
            "iana_timezone": "America/Los_Angeles",
            "push_opt_in": "false",
            "locale_country_code": "US",
            "device_os": "13.0",
            "locale_timezone": "-25200",
            "locale_language_code": "en",
            "location_enabled": "false",
            "background_push_enabled": "false",
            "ua_sdk_version": "12.0.0",
            "location_permission": "UNPROMPTED"
        }
    },
    "body": {
        "name": "purchase",
        "value": 1.5,
        "session_id": "c014a2ed-4c30-4f6d-a9b3-e2ba7a01b45c",
        "source": "API",
        "properties": {
            "device_id": "BB127028-A87C-431B-BF62-32CCF7EB94C9",
            "contentItems": [
                {
                    "$content_schema": "COMMERCE_PRODUCT",
                    "$publicly_indexable": false,
                    "$locally_indexable": false,
                    "$exp_date": 0,
                    "$canonical_identifier": "item/12345",
                    "$og_title": "My Item Title",
                    "$canonical_url": "https://branch.io/item/12345",
                    "$og_description": "",
                    "$og_image_url": "",
                    "$price": 23.2,
                    "$quantity": 1,
                    "$sku": "1994320302",
                    "$product_name": "my_product_name1",
                    "$product_brand": "my_prod_Brand1",
                    "$product_category": "APPAREL_AND_ACCESSORIES",
                    "$product_variant": "XL",
                    "$rating": 0,
                    "$rating_average": 0,
                    "$rating_count": 0,
                    "$rating_max": 0,
                    "$address_street": "",
                    "$address_city": "",
                    "$address_region": "",
                    "$address_country": "",
                    "$address_postal_code": "",
                    "$latitude": 0,
                    "$longitude": 0,
                    "$creation_timestamp": 0,
                    "$currency": "USD"
                }
            ],
            "items": {
                "transaction_id": "12344555",
                "currency": "USD",
                "revenue": 1.5,
                "revenue_in_usd": 1.5,
                "exchange_rate": 1,
                "shipping": 10.2,
                "tax": 12.3,
                "coupon": "test_coupon",
                "affiliation": "test_affiliation",
                "search_query": "item 123",
                "description": "Event_description"
            },
            "transaction": "782362138270294161"
        }
    },
    "type": "CUSTOM"
}