Integrating AppsFlyer and Braze

At a glance: Leverage Braze CRM engagement data and AppsFlyer deep linking capabilities to create seamless email-to-app experiences.

This guide outlines the process of integrating OneLink with Braze email campaigns, providing step-by-step instructions suitable for both marketing professionals and developers. It includes detailed setup procedures for using Braze with either SendGrid or SparkPost as your Email Service Provider (ESP) and offers specific configuration guidance for connecting Braze to the AppsFlyer platform based on your chosen ESP.

1. Set up Braze

To initiate the process of setting up your Braze email account, please reach out to your designated Braze account manager. They will guide you through the necessary steps. Upon completion of the setup, you should have access to the following:

  • Click tracking-domain and Sending domain. Detailed instructions for configuring these can be found in the Braze documentation.
  • SSL Certificate. Guidance on how to acquire an SSL Certificate is available in the Braze documentation.
  • The name of the ESP configured to work with your Braze account (either SendGrid or SparkPost. )

2. Set up OneLink in AppsFlyer

  1. Select a OneLink template in AppsFlyer for your email campaigns. Ensure the template supports Universal Links (iOS) or App Links (Android). To learn how to set Universal Links or App Links in your template, see Add redirection logic for existing app users.
  2. Configure your app to support deep linking with OneLink. To learn more, see the Dev Hub.

3a. SendGrid: Customize the SDK and OneLink

Follow the steps in this section if you selected SendGrid as the ESP for your Braze campaigns. If you selected SparkPost, go to the section below.

Step 1: Configure your app to support Universal Links and App Links

Universal Links (iOS) or App Links (Android) are allowed by the device's operating system to open a specified app when clicked.

Perform the following steps to support Universal and App Links.

iOSAndroid

a. Set up AASA file hosting

Set up the AASA file hosting to enable Universal Links in your emails.

  1. Obtain an Apple App Site Association file (AASA file) in one of the following methods:
    • If you've set up OneLink with Universal Links, you may already have an AASA file associated with OneLink. To obtain the AASA file, perform the following:
      1. Copy the OneLink subdomain of your OneLink template. Ensure the template supports Universal Links (see section 2 above).
      2. Paste it instead of the placeholder in the URL below:<OneLinkSubdomain>.onelink.me/.well-known/apple-app-site-association
      3. To download the AASA file, paste the OneLink URL into your browser's address bar and press Enter. The file will then be downloaded to your computer, and you can open and view its contents using any text editor.
    • Ask your developer to review Apple guide on Universal Links. The guide explains how to create the AASA file.
  2. Host the AASA file in your click-recording domain server. The file should be hosted in the path: click.example.com/.well-known/apple-app-site-association.

    See the SendGrid documentation to learn how to:

    • Configure the AASA file for SendGrid.
    • Set up CDN services to host the AASA file for SendGrid.

 Important!

Once the AASA file is hosted, any change of your OneLink configuration (modification or replacement) requires generating a new AASA file.

 

b. Configure your SDK to support the AASA file

After you host the AASA file in your click-recording domain in the previous step, configure your SDK to support the AASA file.

  1. In Xcode, select your project.
  2. Select Capabilities.

  3. Turn on Associated Domains.
  4. Click (plus), and enter your click domain—for example, applinks:click.example.com.

 

 

Step 2: Configure your app to support deep linking

When a click on the Universal Link occurs, the app is invoked. To enable the app to extract the OneLink behind the click domain and resolve the deep link, perform the following:

iOSAndroid
  1. Provide the click recording domain to the SDK API resolveDeepLinkURLs. This API needs to be called before SDK initialization.
    AppsFlyerLib.shared().resolveDeepLinkURLs = [“click.example.com”,“spgo.io”]
  2. Use the onAppOpenAttribution API to get the deep link parameters and handle the deep link data.

Please see the SDK documentation for more developer information on SDK deep linking support.

Step 3: Sending your first email

  1. Create a OneLink URL on the OneLink management page (or manually). To learn how to create a OneLink link in AppsFlyer see here.
  2. [Best practice] Use the following parameters in the link as the link query parameters:
    • pid (media source): Use a media source that signifies this usage such as Email.
    • c (campaign): Campaign name
    • af_dp: The deep link URI scheme you want to deep-link your users into.
    • af_web_dp: Where to redirect users clicking the link on the desktop.
    • af_ios_url: Where to redirect users who don’t have the app after clicking the link on an iOS device.
    • af_android_urlWhere to redirect users who don’t have the app when they click the link on an Android device.
  3. URL-encode all parameter values.
  4. To enable Universal linking for the link, include the attribute universal=true in the HTML link tag of your email template, for example:

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

    Note that SendGrid adds the /uni/ parameter when universal=true attribute is included to the HTML link element, to learn more see the SendGrid documentation.

  5. If the email is retargeting existing users, add to OneLink the parameter is_retargeting=true. This converts the attribution link from a user acquisition type URL to a retargeting URL. To learn more about retargeting attribution, see here.
  6. Place the OneLink URL in the email you are creating in the Braze Design Editor.

     Example

    For the sake of readability, URL parameters are not URL encoded in this example:

    https://example.onelink.me/abcd?pid=Email&c=Spring_Newsletter&is_retargeting=true&
    af_dp=testapp://path/to/content&af_web_dp=https://www.example.com/path/to/content&
    af_ios_url=https://www.example.com/path/to/content&af_android_url=https://www.example.com/path/to/content

    SendGrid wraps the above link with the click recording domain that you set in the previous steps.

  7. Insert the OneLink URL in the message and send it to your mail address.

The following outcomes constitute a successful test:

  • If you have the app installed, the app is invoked.
  • If the relevant AppsFlyer SDK deep linking APIs are implemented you are redirected to the relevant contents within your app.
  • The click appears in the AppsFlyer dashboard, attributed to the provided media source and campaign.
  • The click is registered in Braze.

3b. SparkPost: Customize the SDK and OneLink

Follow the steps in this section if you selected SparkPost as the ESP for your Braze campaigns. If you chose SendGrid, go to the section above.

Step 1: Configure your SDK to support Universal Links and App Links

Universal Links (iOS) or App Links (Android) are allowed by the device's operating system to open a specified app when clicked.

Perform the following steps to support Universal and App Links.

iOSAndroid

a. Set up AASA hosting and custom link sub-path

Set up the AASA file hosting to enable Universal Links in your emails.

  1. Obtain an Apple App Site Association file (AASA file) in one of the following methods:
    • If you've set up OneLink with Universal Links, you may already have an AASA file associated with OneLink. To obtain the AASA file, perform the following:
      1. Copy the OneLink subdomain of your OneLink template. Ensure the template supports Universal Links (see section 2 above).
      2. Paste it instead of the placeholder in the URL below:<OneLinkSubdomain>.onelink.me/.well-known/apple-app-site-association
      3. To download the AASA file, simply paste the OneLink URL into your browser's address bar and press Enter. The file will then be downloaded to your computer, and you can open and view its contents using any text editor.
    • Ask your developer to review Apple guide on Universal Links. The guide explains how to create the AASA file.
  2. Host the AASA file in your click-recording domain server. The file should be hosted in the path: click.example.com/.well-known/assetlinks.json.

    See the SparkPost documentation to learn how to:

    • Configure the AASA file for SparkPost.
    • Set custom link sub-paths.

     Important!

    Once the AASA file is hosted, any change of your OneLink configuration (modification or replacement) requires generating a new AASA file.

b. Redirect your click-tracking domain to your AASA file host

In your DNS server perform the following after your click-tracking domain is verified in Braze (to learn more about click-tracking domain verification, see the Braze documentation):

  1. Delete the CNAME record that redirects your subdomain to the SparkPost domain.

     Note

    You created the record as part of your Braze [mail account/campaign] configuration process. To learn more see the Braze documentation.

  2. Create a CNAME record that redirects your click-tracking domain to the CDN hosting your app AASA file, instead of the record you deleted above.

c. Configure your SDK to support the AASA file

After you host the AASA file in your click-recording domain in the previous step, configure your SDK to support the AASA file.

  1. In Xcode, select your project.
  2. Select Capabilities.

  3. Turn on Associated Domains.
  4. Click (plus), enter your click domain, for example, applinks:click.example.com.

 

 

Step 2: Configure your SDK to support deep linking

When a click on the Universal Link occurs, the app is opened and the SDK is initiated. To enable the SDK to extract the OneLink behind the click domain, perform the following:

iOSAndroid
  1. List the click domains in the SDK property  resolveDeepLinkURLs. Make sure to set this property before SDK initialization.
  2. Make sure that List spgo.io is one of the listed domains. SparkPost owns this domain and it's part of the redirection flow.
    AppsFlyerLib.shared().resolveDeepLinkURLs = [“click.example.com”,“spgo.io”]
  3. Use the onAppOpenAttribution API to get the deep link parameters and handle the deep link data.

For more developer information on SDK deep linking support please see the SDK documentation here.

Step 3: Sending your first email

  1. Create a OneLink URL on the OneLink management page (or manually). To learn how to create a OneLink link in AppsFlyer see here.
  2. [Best practice] Use the following parameters in the link as the link query parameters:
    • pid (media source): Use a media source that signifies this usage such as Email.
    • c (campaign): Campaign name
    • af_dp: The deep link URI scheme you want to deep-link your users into.
    • af_web_dp: Where to redirect users clicking the link on desktop.
    • af_ios_url: Where to redirect users that don’t have the app clicking the link on an iOS device.
    • af_android_urlWhere to redirect users that don’t have the app click the link on an Android device.
  3. URL-encode all parameter values.
  4. To enable Universal or App linking for the link, include the data-msys-sublink attribute in the HTML link tag of your email template, for example: <a href="links.example.com data-msys-sublink="open-in-app">Link to your app!</a> To learn more see the SparkPost documentation.
  5. If the email is part of a retargeting campaign, add the parameter is_retargeting=true.This indicates that the attribution link is from a retargeting campaign. Learn more about retargeting.
  6. Place the OneLink URL in the email you are creating in the Braze Design Editor.

     Example

    For the sake of readability, URL parameters are not URL encoded in this example:

    https://example.onelink.me/abcd?pid=Email&c=Spring_Newsletter&is_retargeting=true&af_dp=testapp://path/to/content&af_web_dp=https://www.example.com/path/to/content&af_ios_url=https://www.example.com/path/to/content&af_android_url=https://www.example.com/path/to/content

    SparkPost wraps the above link with the click recording domain that you set in the previous steps.

  7. Insert the OneLink URL in the message and send it to your mail address.

The following outcomes constitute a successful test:

  • If you have the app installed, the app is invoked.
  • If the relevant AppsFlyer SDK deep linking APIs are implemented you are redirected to the relevant contents within your app.
  • The click appears in the AppsFlyer dashboard, attributed to the provided media source and campaign.
  • The click is registered in Braze.