Zeta

Setup

This guide will walk you through how to integrate your email service provider with Branch. If you have not completed the getting started steps, please follow this documentation first.

Configure your ESP

To open the app directly on iOS 9.2+, you must configure your email integration and your app to support Universal Links in emails.

Tell us your click tracking domain

You can retrieve your click tracking domains from your Zeta settings. On Done click, an AASA file - required for Universal Links - specific to that domain will be generated.

Configure your app for your click tracking domain

image

In this prompt, enter the email of someone on your team who is qualified to modify your iOS app, and then click Send. They will complete the technical setup steps below.

Technical setup

The following app changes ensure that your email integration supports Universal Links. You will need access to your app code to make these changes.

You should have received an email from Branch with your ESP's click tracking domain. If not, likely you or someone on your team still needs to complete the Deep Linked Email setup flow.

How does it work?

Apple recognizes the click tracking domain as a Universal Link, and opens the app immediately without the browser opening. Once the app has opened, Branch will collect the referring URL that opened the app (at this time, it will be the click tracking url). Inside the app, Branch will robotically “click” the link, registering the click with the ESP, and returning the Branch link information to the Branch SDK inside the app. This information is then used to deep link the user to the correct in-app content. See the Support section for more information.

Set up your click tracking domain

Create a CNAME for your click tracking domain and point it to thirdparty.bnc.lt.

Add your click tracking domain to your Associated Domains

To enable Universal Links on your click tracking domain, you'll need to add the click tracking domain to your Associated Domains entitlement.

  1. In Xcode, go to the Capabilities tab of your project file.
  2. Scroll down and enable Associated Domains if it is not already enabled.

    image

  3. Copy your click tracking domain from the email you received from Branch, or retrieve it from your ESP's settings.

  4. In the Domains section, click the + icon and add your click tracking domain. For example, if your click tracking domain is email.example.com, add an entry for applinks:email.example.com.

    image

Having trouble or new to Universal Links?

Follow these instructions for more details on enabling Universal Links in the Branch dashboard and in Xcode.

If you have links to content that exists only on web, and not in the app (for example, a temporary marketing webpage that isn't in the app) then this code snippet will ensure all links that have not had the deep linking script applied will open in a browser.

You should add this code snippet inside the deep link handler code block. Note that this uses query parameter $web_only=true. This should match the query parameter on the web URL you enter in the email.

[branch initSessionWithLaunchOptions:launchOptions andRegisterDeepLinkHandler:^(NSDictionary *params, NSError *error) {
  // params are the deep linked params associated with the link that the user clicked before showing up.
  if (params[@"$3p"] && params[@"$web_only"]) {
            NSURL *url = [NSURL URLWithString:params[@"$original_url"]];
            if (url) {
                [application openURL:url]; // check to make sure your existing deep linking logic, if any, is not executed, perhaps by returning early
            }
  } else { 
    // it is a deep link
    GDLog(@"branch deep link: %@", [params description]); 
    [self handleBranchDeeplink:params];
  }
}];

Validate and test

image

The last step of the Deep Linked Email setup flow validates whether you have completed all necessary steps and whether an engineer on your team has completed the technical setup steps. You will also see recommendations for how to improve your email integration.

Usage

Once you’ve completed the one time setup steps, it’s time to send your first email.

This guide will identify which web links you'd like to open the app and deep link, as well as convert them to Branch links.

For the email links that you would like to deep link to content, add $deep_link=true to the URL as a query parameter, for example:

<a href="links.example.com?$deep_link=true" >Link to your app!</a>

This will ensure that your links are converted to Branch links that will open the app on iOS and Android, with full tracking and attribution.

With your email service provider, all email links will open the app by default. In order for your app to know that the email link should bounce to web after opening the app, add $web_only=true to your links as a query parameter, for example:

<a href="links.example.com?$web_only=true" >Link to your app!</a>

Handle links for web-only content

Make sure you have completed the technical setup steps to handle web-only links within your app.

This will also ensure that your links are converted to Branch links that will open the app on Android as well, with full tracking and attribution.

What happens to your links behind the scenes?

This is what a link looks like within your email template:

http://example.com/?foo=bar

When a user clicks your link, Branch processes the link and converts it to something like this:

https://vza3.app.link/3p?%243p=e_xx&%24original_url=http%3A%2F%2Fexample.com%2F%3Ffoo%3Dbar

Where vza3.app.link is your Branch domain.

The conversion to Branch links will only work when your links are wrapped in your click tracking domain. To test links without wrapping, please generate a test link on step 3 of email onboarding, also accessible by clicking the gear icon for your ESP on the email page.

image

More information

Curious about how email works and more FAQ? Visit our general email support page.

Comments