Salesforce

Prerequisites

  • You must have the Salesforce Marketing Cloud Sender Authentication Package (SAP) in order to benefit from Universal Links + click tracking functionality.

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 Salesforce settings. We highly recommend using a new click tracking domain for this implementation to ensure that the user experience for pre-Branch links on the original click tracking domain doesn't break.

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.

Configure your AASA file in Salesforce Marketing Cloud

Your Salesforce account must be configured to correctly handle Universal Links. Configure the settings in Deep Linking under the Admin section in Email Studio. Ensure you're in the account corresponding to the correct click tracking domain you selected above.

image

  1. Enter the AppID value
  2. Check the "Exclude Profile" and "Unsub Center" checkboxes to force links to these items to open in the browser and not the app, if desired.
  3. Click "Save" to save the configuration.
  4. Let Salesforce and Branch know that you've finished this step and your Technical Account Manager will verify that everything looks good.

image

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 + Salesforce. You will need to replace the web URLs in your templates with these. To create Branch links, you can either:

  1. Add a new Content Area for easy deep linking
  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

Add a new Content Area for easy deep linking

In this step, we'll add a new Content Area in Salesforce that makes it very easy to create deep links in your emails.

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

    %%[ VAR @deeplink, @branch_base_url SET @branch_base_url = "https://DOMAIN-HERE/3p?%243p=e_et" SET @deeplink = CONCAT(@branch_base_url, CONCAT("&%24original_url=", URLEncode(@link_to_be_wrapped, 1, 1))) ]%%
    
  2. After logging into Salesforce Marketing Cloud, click on Email Studio and then a sub-menu will appear. Click on Email in the dropdown menu:

    image

  3. This will take you to the landing page for the Email section. Click on Content in the menu bar to navigate to the Content section:

    image

  4. In the Content section, you will see a list of folders on the left side. Right click on the My Contents folder and choose New Folder in the context menu:

    image

  5. Name the folder Branch:

    image

  6. Once the folder is created, click on the Branch folder. On the right side, you will see a menu bar for the Branch folder. Click on Create and in the sub menu, click Content to create new content:

    image

  7. In the Create Content window that appears, enter deeplink in the text field named Content Name. Click on Next after you enter the text:

    image

  8. The next screen will ask you to select the format of the content. Choose Free Form and then click Next:

    image

  9. In the next screen, paste in the snippet you generated in 1:

    image

  10. Click Save. You will now be back at your list of folders in the Content section with the file deeplink listed:

    image

You have now successfully created the deep linking script.

Code snippet

The snippet will follow this format:

%%[ VAR @deeplink, @branch_base_url SET @branch_base_url = "BASE URL FROM BRANCH" SET @deeplink = CONCAT(@branch_base_url, CONCAT("&%24original_url=", URLEncode(@link_to_be_wrapped, 1, 1))) ]%%
The code above has a placeholder for @branch_base_url. Replace it with yours.

Configure your Salesforce email templates

This section covers how to convert individual links in your existing email templates to use Branch deep links. You will need to determine which links in your email template that you want to convert to Branch deep links.

To convert a link to a Branch deep link, let's use an example:

<a style="border-radius: 4px;display: inline-block;font-size: 14px;font-weight: bold;line-height: 24px;padding: 12px 24px;text-align: center;text-decoration: none !important;transition: opacity 0.1s ease-in;color: #fff;background-color: #00afd1;font-family: sans-serif;" href="https://www.blueapron.com/recipes/five-spice-chicken-vermicelli-with-mushrooms-collard-greens-baby-fennel">I want it!</a>

This is what the link will look like after you have modified it to support Branch deep links:

%%[ SET @link_to_be_wrapped = "https://www.blueapron.com/recipes/five-spice-chicken-vermicelli-with-mushrooms-collard-greens-baby-fennel" ContentAreaByName("My Contents\deeplink") ]%%
<a style="border-radius: 4px;display: inline-block;font-size: 14px;font-weight: bold;line-height: 24px;padding: 12px 24px;text-align: center;text-decoration: none !important;transition: opacity 0.1s ease-in;color: #fff;background-color: #00afd1;font-family: sans-serif;"  href="%%=RedirectTo(@deeplink)=%%">I want this!</a>

We recommend you create the deep link in a separate document and then paste it back into the HTML editor in Salesforce marketing cloud. To begin:

  1. Log in to Salesforce Marketing Cloud
  2. Click on Email Studio and then a sub-menu will appear. Click on Email in the dropdown menu:

    image

  3. This will take you to the landing page for the Email section. Click on Content in the menu bar to navigate to the Content section:

    image

  4. Navigate to your folder containing your emails and open an existing email. Make sure the email is in HTML layout as shown below:

    image

  5. Choose a link that you want to convert to a Branch deep link. Copy the text right after the href= in your email template, and paste it into a separate document. In the example, it is:

    "https://www.blueapron.com/recipes/five-spice-chicken-vermicelli-with-mushrooms-collard-greens-baby-fennel"

  6. Add %%[ SET @link_to_be_wrapped = before the link in your separate document. In the example, this is now:

    %%[ SET @link_to_be_wrapped ="https://www.blueapron.com/recipes/five-spice-chicken-vermicelli-with-mushrooms-collard-greens-baby-fennel"

  7. Add ContentAreaByName("My Contents\deeplink")]%% after the link:

    %%[ SET @link_to_be_wrapped = "https://www.blueapron.com/recipes/five-spice-chicken-vermicelli-with-mushrooms-collard-greens-baby-fennel"ContentAreaByName("My Contents\deeplink")]%%

  8. From the original link in your template, copy the text from and including <a until the href=. Add it to the text after %% in the last step. Please include the <a but not the href=:

    %%[ SET @link_to_be_wrapped = "https://www.blueapron.com/recipes/five-spice-chicken-vermicelli-with-mushrooms-collard-greens-baby-fennel" ContentAreaByName("My Contents\deeplink") ]%%<a style="border-radius: 4px;display: inline-block;font-size: 14px;font-weight: bold;line-height: 24px;padding: 12px 24px;text-align: center;text-decoration: none !important;transition: opacity 0.1s ease-in;color: #fff;background-color: #00afd1;font-family: sans-serif;"

  9. Add href="%%=RedirectTo(@deeplink)=%%" to the end:

    %%[ SET @link_to_be_wrapped = "https://www.blueapron.com/recipes/five-spice-chicken-vermicelli-with-mushrooms-collard-greens-baby-fennel" ContentAreaByName("My Contents\deeplink") ]%% <a style="border-radius: 4px;display: inline-block;font-size: 14px;font-weight: bold;line-height: 24px;padding: 12px 24px;text-align: center;text-decoration: none !important;transition: opacity 0.1s ease-in;color: #fff;background-color: #00afd1;font-family: sans-serif;"href="%%=RedirectTo(@deeplink)=%%"

  10. From the original link in your template, copy the end of the tag, the link text, and the closing tag (>I want it!</a> in the example) and add it to the end:

    %%[ SET @link_to_be_wrapped = "https://www.blueapron.com/recipes/five-spice-chicken-vermicelli-with-mushrooms-collard-greens-baby-fennel" ContentAreaByName("My Contents\deeplink") ]%% <a style="border-radius: 4px;display: inline-block;font-size: 14px;font-weight: bold;line-height: 24px;padding: 12px 24px;text-align: center;text-decoration: none !important;transition: opacity 0.1s ease-in;color: #fff;background-color: #00afd1;font-family: sans-serif;" href="%%=RedirectTo(@deeplink)=%%">I want it!</a>

  11. Copy your final result from the separate document back into your email template, replacing everything inside and including the <a></a> tags in the template.

  12. Repeat this for all your links in your email template that you want to convert to Branch deep links.

These links are complete and will deep link to content in your app.

This converted code is referred to as the "Branch script" - this script will convert your web URLs to deep links. The script uses the Content Area to turn your web URL into a deep link.

Adding the Branch script

Wherever you are using <a> tags in your email templates, replace those with a short snippet for web URLs that you would like to deep link.

%%[SET @link_to_be_wrapped = "ADD YOUR LINK HERE" ContentAreaByName("My Contents\deeplink")]%%
<a href="%%=RedirectTo(@deeplink)=%%">Click Me</a>
For example, before: <a href="https://branch.io/product/1234">Example link</a> After: %%[ SET @link_to_be_wrapped = "https://branch.io/product/1234" ContentAreaByName("My Contents\deeplink") ]%% <a href="%%=RedirectTo(@deeplink)=%%">Example link</a>

Content Area folder

Make sure your deeplink Content Area is in the right folder. Either change the folder to "My Contents" or change the path used by "ContentAreaByName" in the Branch script.

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.

If you want any web-only links to not open the app on iOS, Salesforce has a special attribute that you can apply to these links.

Add mc-deep-link="false" to your link tag like this:

<a mc-deep-link="false" href="https://my.app.link/3p?$3p=e_et&$original_url=..." >This link will not open the app.</a>

To ensure that the app does not open on other platforms, add %24web_only%3Dtrue to your links as a query parameter, for example:

<a href="https://vza3.app.link/3p?%243p=e_xx&%24original_url=http%3A%2F%2Fexample.com%2F%3Ffoo%3Dbar%24web_only%3Dtrue" >Link to your app!</a>

More information

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

Comments