Responsys

Prerequisites

  • You must have an EMD (Email Message Designer) enabled account in order to use the Branch integration. If you do not have one, or if you’re not sure, please talk to your Responsys Account Manager.

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 domain from your Responsys settings. Enter it in item 1 of this step. On Done click, an AASA file - required for Universal Links - specific to that domain will be generated.

Send your AASA file to your ESP

image

Your AASA file must be uploaded to your click tracking domain by your email service provider. Your ESP account manager will do this for you - enter their email and click Send, and they will receive an email with the file and request to upload.

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.

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.

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.

There are a few different ways you can create Branch links that are compatible with Deep Linked Email + Responsys. You will need to replace the web URLs in your templates with these. To create Branch links, you can either:

  1. Use the Branch Responsys SDK
  2. Making regular Branch links compatible with email
  3. Create email links via API without changing your email templates
  4. Convert all web links in your email to deep links

Responsys uses the shortcode e_rs for links in emails - please use this in place of e_xx in the guide below.

Use the Branch Responsys SDK

In this step, we'll upload an SDK that makes it very easy to create deep links in your emails.

Watch how to do this instead

There is also a tutorial video that walks through these steps.

  1. Work with your Branch account manager to modify the following code snippet, replacing DOMAIN-HERE with your Branch base domain:

    <#macro deeplink link_to_be_wrapped><#assign branch_base_url="https://DOMAIN-HERE/3p?%243p=e_rs"><#assign final_link=branch_base_url + "&%24original_url=" + link_to_be_wrapped?url("ISO-8859-1")><a href="${final_link}"><#nested></a></#macro> <#macro tracked_deeplink link_to_be_wrapped><#assign branch_base_url="https://DOMAIN-HERE/3p?%243p=e_rs"><#assign deeplink=branch_base_url + "&%24original_url=" + link_to_be_wrapped?url("ISO-8859-1")></#macro>
    
  2. Log in to your Responsys account.

  3. In the Responsys Dashboard, open your Content Library. You can also access it via the Shortcuts screen on the main page:

    image

  4. Once you are in the Content Manager, you’ll see a list of folders where content is stored. Under All Content, create a new folder named Branch_SDK:

    image

  5. Select the Branch_SDK folder and then click Create Document:

    image

  6. In the Create Document window:

    • Enter branch-sdk in the “Document Name” field.
    • In the Content Box, delete all the text.
    • Paste the snippet you copied in 1.
    • Click Save.

    image

You have now successfully created the deep linking script. Your file structure should look as follows:

image

Configure your Responsys email templates

This code is referred to as the "Branch script" - this script will convert your web URLs to deep links.

The Responsys integration requires you to add email template code in two places.

  1. At the top of an email template
  2. Immediately before a hyperlink

Copy the following snippet, and using the “Source” view, paste the snippet directly under the <html> tag for every template you plan to add deep linking to.

<#include "cms://contentlibrary/Branch_SDK/branch-sdk.htm">

Wherever you are using <a> tags in your email templates, replace those with <@deeplink> tags, or add <@tracked_deeplink /> for web URLs that you would like to deep link.

Here's how it looks with Link Tracking disabled.

Before: <a href="https://branch.io">Example link</a>

After: <@deeplink "https://branch.io">Example link</@deeplink>

With link tracking enabled, you can still use Branch links in emails.

Before: <a href="https://branch.io/product/1234">Example link</a>

After: <@tracked_deeplink "https://branch.io/product/1234" /> <a href="${clickthrough('TEST_TRACKED_DEEPLINK' , 'deeplink=' + deeplink)}">Example link</a>

This latter example pulls from a Link Table. In the link table, set the IOS Link URL and Android link URL to the value ${deeplink}.

image

Be sure to add "$3p":"e_xx" to the deep link data of any links you use in email to ensure Universal Link and click tracking works as expected.

To create email links via API, please use the instructions on how to create links via API, but include the following key value pairs in your call:

  1. "$3p":"e_xx" This is required for Universal Link and click tracking functionality.
  2. "$original_url":"{{your web url URI encoded}}" For each piece of content, include a URI encoded version of your content's web URL. You can also add deep link data as query parameters on that web URL. This ensures accurate Content Analytics reporting. Example: "$original_url":"https%3A%2F%2Fshop.com%2Fshoes%2Fbrown-shoes%3Fmy_key%3Dmy_value%26campaign%3Dshoe_discounts"

We have provided a way of easily converting web links to Branch links, as well as an example. The example takes an html email (as a string) and applies the script to it.

Here is the script:

var crypto = require('crypto');
module.exports = function(original_url, branch_base_url) {
    if (!original_url) { return new Error('Missing original_url'); }
    if (typeof original_url != 'string') { return new Error('Invalid original_url'); }
    if (!branch_base_url) { return new Error('Missing branch_base_url, should be similar to https://bnc.lt/abcd/3p?%243p=e_xx'); }
    if (typeof branch_base_url != 'string') { return new Error('Invalid branch_base_url'); }

    return branch_base_url + '&%24original_url=' + encodeURIComponent(original_url);
};

Here is how links look before and after (the latter being a Branch deep link).

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

Note that these are simplified examples, not actual demo links.

In some cases you may have content on web that isn’t in the app - for example, a temporary Mother’s Day promotion or an unsubscribe button. You can designate links to only open on web if you use the Responsys Link Table feature. There are three URL fields in the link table when creating a new link: LINK_URL, IOS_LINK_URL, and ANDROID_LINK_URL. If you only enter the link in the LINK_URL field, the path of the final click-wrapped url will begin with /pub/cc, whereas if you input an IOS_LINK_URL, then the path of the final click-wrapped url will begin with pub/acc. You should set up your AASA file to whitelist only the path /pub/acc* in order to not launch the app from web-only links.

image

image

Support

Styling

If you include style tags within your <a> tags, you’ll need to separate those out into a separate div inside the <@deeplink> tag. If you use tracked links with <a> tags, those will work fine.

Style Tags within your anchor tags like so:

Before:

<a href="https://branch.io/" style="color:#000001; text-decoration:none;">Branch Website</a>

After:

<@deeplink "https://branch.io/"><div style="color:#000001; text-decoration:none;">Branch Website</div></@deeplink>

Launch failed error

You’ll see this error if you haven’t included the <#import > snippet in your template.

Launch Failed: Launch failed: Template /contentlibrary/branch test campaign/My Default Template.htm caused an execution error: on line 183, column 92 in cms://contentlibrary/branch test campaign/Content.htm: deeplink is not a user-defined directive. It is a freemarker.template.SimpleScalar

Using dynamic data from profile extension tables

The <@deeplink > and <@tracked_deeplink /> tags even work with dynamic links injected via RPL.

<@deeplink "${latestProduct.url}">${latestProduct.name}</@deeplink>

More information

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

Comments