ESPs (Email Service Providers) can be excellent sources for segmented user traffic.
One of the problems with ESPs is recording clicks while still persevering deep linking functionality. ESPs wrap the deep linking URL with their own ESP's click recording domain. This procedure often times breaks the iOS Universal Links process.
However, with ESPs that support Universal Links on top of their click recording domain, deep linking and click recording can still be performed.
This article explains the flow for integrating OneLink-based attribution links into your SendGrid based email system in order to seamlessly deep link from emails. The integration utilizes SendGrid’s support for Universal Links on top of the branded click recording domain.
- AppsFlyer iOS SDK version 4.9.0
- AppsFlyer Android SDK version 4.9.0
SendGrid doesn’t support Android App Links. However, URI Scheme deep linking is still supported. No special actions are required to support deep linking in Android apps from SendGrid.
Setting up SendGrid
Step 1: Set up link branding in SendGrid
In order to use Universal Links with SendGrid, you need to create a dedicated click recording domain and set a subdomain (e.g. click.example.com).
This can be done by purchasing a designated domain, or using your own domain.
Subdomain configuration is accessible in SendGrid via “Advance Settings”, by checking the “Use a custom link subdomain” and adding your subdomain:
Step 2: Set up SSL for click recording
After you set click recording domain and Link Branding, follow SendGrid's instructions on how to enable SSL click and open recording for an authenticated domain.
Step 3: Apple app site association file (aasa) hosting
- There are two ways to obtain an aasa
- Ask your developer to review Apple's guide on universal links. The guide explains how to create the aasa.
- Alternatively, if you setup OneLink with Universal Links, you might already have an aasa associated with the OneLink. To obtain the aasa, go to OneLink configuration, find a OneLink that is configured with Universal Links and obtain the OneLink ID. The OneLink ID appears on the first column of the table that lists all existing OneLink configurations. Once you have the ID, paste the to the following URL in the browser address bar and hit enter: <OneLinkSubdomain>.onelink.me/.well-known/apple-app-site-association. When you do so, the aasa file is downloaded to your computer. You can open it using any simple text editor.
- Host the AASA in your click recording domain server. The file should be hosted in the path: click.example.com/.well-known/apple-app-site-association.
Once the AASA file is hosted, any change of your OneLink configuration (either modification or replacement) requires generating new AASA file.
Step 4: Configuring your AppsFlyer SDK
If you haven’t already done so, make sure you have configured your app to support deep linking with OneLink.
After configuring your click recording domain to support Universal Links as described previously, you will need to set up your app to deep link and resolve that Universal Link.
- Associate the click recording domain in Xcode:
- Provide the click recording domain to the SDK API
setResolveDeepLinkURLs. This API needs to be called before SDK initialization. For more information please refer to SDK documentation here.
[[AppsFlyerTracker sharedTracker] setResolveDeepLinkURLs:@[@"click.example.com"]];
- When the app is invoked due to a click on the Universal Link, the AppsFlyer SDK resolves the deep link and extracts the underlying OneLink. All deep link parameters are then propagated into the onAppOpenAttribution API for deep link logic execution.
Step 5: Sending your first email
- Create a OneLink URL in the Link Management page (or manually)
- When creating the OneLink URL make sure to URL encode all parameter values
- The following parameters are highly recommended to use:
- pid (media source) - Use a media source that signifies this usage such as Email.
- c (campaign) - The name of the campaign you want to measure
- 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 in an iOS device
- af_android_url - Where to redirect users that don’t have the app click the link in an Android device
- Place the OneLink URL in the email you are creating in SendGrid's Code Editor or Design Editor. To enable Universal Links for it, include the attribute "universal=true" in the HTML link tag of your email template. Example:
Note that SendGrid adds the `/uni/` parameter when "universal=true" is included.
<a href="links.example.com" universal="true">Link to your app!</a>
- If the email is retargeting existing users, add to OneLink the parameter
This converts the attribution link from a user acquisition type URL to a retargeting URL. Learn more.
- At this stage, SendGrid wraps the above link with the click recording domain that you set in the previous steps. Any click on the click recording domain will redirect to the OneLink attribution link.
URL parameters are not URL encoded in this example, just for the sake of readability:
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
Step 6: Testing your links
After following all the required steps mentioned above, creating the appropriate OneLink URL, and placing it in an email, send yourself a test email.
What should you expect?
If you have the app installed, the app should be invoked. If the relevant AppsFlyer SDK deep linking APIs are implemented you should be deep linked into the relevant content.
In addition, a click should appear in both the AppsFlyer dashboard, attributed to the provided media source and campaign, and also in SendGrid's data