Braze/SendGrid Email Service Provider (ESP) Attribution Integration

Follow
Avatar
Travis Simpson
Updated

Singular's integration with SendGrid lets you measure app installs and re-engagements with SendGrid emails that wrap your deep-link-enabled Singular Links.

While link wrapping usually breaks the deep link experience, this integration allows you to serve deep links as well as measure attributions to both installs and app opens from emails driving users into your mobile app.

The integration is based on a deep-link-enabled click tracking domain (CTD) configured in SendGrid. When emails that include Singular Links are served to your users, SendGrid automatically wraps any Singular Link used in your email. Users who don't have the app installed will be redirected to the fallback configured in your Singular Links. Users who install the app are measured as an app install attributed to the Singular Link.

Returning users will be deep-linked into the app, where deep link handling is handled through your Singular SDK implementation. These users are measured as Re-Engagements to the Singular Link.

Prerequisites

  • Singular Links for iOS and Android
  • Singular SDKs
    • iOS SDK 11.0.0+
    • Android SDK 11.0.0+

Setup Instructions

1

Set Up Link Branding in SendGrid

In order for universal links to work from the ESP link click, first you must configure a custom tracking domain to use in Sendgrid. If using your own domain, you can use a subdomain like this, for example: click.mydomain.com.

  • Subdomain configuration can be found in SendGrid in “Advance Settings” → “Use a custom link subdomain” → add your subdomain:

  • See SendGrid’s documentation for configuring link branding - 
2

Set Up SSL Click Recording

You must include an SSL certificate in your Sendgrid account. See SendGrid’s documentation. 
3

Configure Branded Link Domains for Universal Links

  • Have your App Developer create an AASA file as described in Apple's documentation with the branded link domain configured in Step 1.
    • Once the AASA file is created, it should be hosted in your click recording domain server in the path click.yourdomain.com/.well-known/apple-app-site-association
4

Update Singular SDK Implementation

Register the SendGrid branded link domain as an ESP domain, prior to initializing the Singular SDK. This allows the Singular SDK to recognize the branded link domain opening the app, allowing the Singular SDK to handle the deep link and attribution the re-engagement.

iOS:

SingularConfig* config = [[SingularConfig alloc] initWithApiKey:apiKey andSecret:secretKey];
config.espDomains = @[@"click.mydomain.com"];

Android:

SingularConfig config = new SingularConfig(apiKey, secretKey)
.withESPDomains(Arrays.asList("click.mydomain.com"));
5

Set Up Email

Create a deep link enabled Singular Link for your SendGrid email

  • Verify that it has the proper deep link destination(s) enabled and it is configured for ReEngagement Tracking.
  • Be sure to append any reporting parameter you'd like to use for reporting via link parameters.  See all supported granularity parameters.
6

Add Singular Link to Email and Test

Add your Singular Link in the email you are creating using  SendGrid's Code/Design Editor. To enable Universal Links in the email, include the attribute "universal=true" in the HTML link tag of your email template. Example:

<a href="click.yourdomain.com" universal="true">Open in the App</a>

Note: Per their documentation: “SendGrid adds the /uni/ parameter to flagged universal links”

Expected Behavior:

When users click on the link in the email, the partner will wrap the Singular Link with your click tracking domain. In the case of a returning user clicking the link, the user will deep link into the app, and the Singular SDK will measure the app open engagement since the click tracking domain is registered in the Singular SDK. If the user doesn’t have the app installed, they will be redirected to the “if app not installed” fallback url configured on the Singular link.

Notes and Tips:

  • Attributions for SendGrid emails work just like any other attributions based on Singular Links. For more information, see Singular Links and Tracking Link Parameters.
  • If your deep link is not working:
    • Ensure your custom tracking domain and destination paths are properly configured in SendGrid. This includes uploading the proper Apple App Site Association file for your app.
    • Ensure that the Singular Link embedded in your emails is also configured with deep linking. You can tell if a Singular Link has deep linking enabled if it has a _dl= parameter in the URL.