Universal links allow the links you send through Bloomreach Engagement to open directly in your native mobile application without any redirects that would hinder your users' experience.

How can universal links improve your users' experience

Without using universal links, all email links sent through Bloomreach Engagement now open our tracking URL, which usually looks something like https://cdn.exponea.com/project-slug/e/some-unique-token/click. This URL will automatically redirect your user to the original URL very fast without the user noticing the redirect. This works smoothly when the original URL is your website. However, if you want your link to open a mobile application, this will create a bad user experience because the link will first open the browser to track the click. Only then will it be redirected to your mobile app. This is something the user will definitely notice. With universal links, you can skip this undesirable behavior, redirection to the browser while preserving the desired behavior, then click on the link being tracked.

In short, universal links allow you to avoid the unpleasant visual flickering of opening multiple applications in your users' mobile devices while still maintaining the desired functionality of keeping your data in Bloomreach Engagement.

📘

Using universal links

If you are not interested in all of the technical details but just need help using them, skip to Using universal links.

How does it work

On your custom domain, such as www.client.com, set up the www.client.com as a universal link in your app. This will make the links from e-mails sent through Bloomreach Engagement open directly in your mobile application, when installed, without having to go through the browser. Moreover, Bloomreach Engagement SDK in the application will also recognize this link as a Bloomreach Engagement link and track the click action for reporting purposes.

📘

What if the user does not have the application?

If your users do not have the application, even with universal links put in place, the user experience will not change from the previous approaches. In other words, users without your application, or desktop users, will be redirected to their browser.

Requirements

SDK requirements

The required SDK release for universal links is 2.4.0 for Android and 2.3.0 for iOS. If you are using an older SDK, the universal links will not properly function; see Using universal links with old SDKs.

Application domain

Each of your applications needs to have its proper domain that will be able to validate the merging of the app's cookie or identity with the ITT (transfer identity) parsed identity on the server and logs correctly. The domain should also support the configurable option of opening the links in the default system browser or the application's own built-in web view, which needs to be provided by the app developer.

Cases to be considered

• If the application is not installed, the universal link will retain the original functionality meaning the link will be opened in a browser, which is desirable.
• If the emails are being sent from a different project than the one that the SDK of the website is initialized to, the click will not be tracked on the other project

🚧

Instances and tracking

Event campaign clicks are tracked to the customer identified with iitt (recipient) into the project where the SDK was initialized - this must be the same project, otherwise the events will be discarded and you will lose click tracking for reporting purposes.

Setting up the universal link support

To achieve the behavior described previously, it is recommended to use universal links on iOS and App Links on Android. Both of these approaches will be described below.

1. iOS - Universal Links

Universal links ensure that an app is linked to a domain (and specific paths) that opens the app instead of the browser. They can be configured to open different apps based on differences in the path of the URLs.

Requirements for iOS universal links

Web requirements:
The domain used for universal links needs to have the Apple App Site Association (AASA) file configured on the webserver to be served over HTTPS in the root of the domain or under the well-known slug.

{
  "plist": {
    "dict": {
      "key": "com.apple.developer.associated-domains",
      "array": {
        "string": "applinks:www.client.com"
      }
    }
  }
}

Application requirements:
Your app needs to add support for universal links by changing project configuration, enabling universal link capability, and specifying the desired domain.

To make sure that clicks are properly tracked, you should invoke Bloomreach Engagement iOS SDK's trackCampaignClick method in the App Delegate (find more in the link below).

Links to documentation

Apple - Enabling Universal Links
Apple - Support Universal Links
Bloomreach Engagement iOS SDK - Tracking Universal Links

2. Android - App Links

Similarly to iOS - App Links allow websites to be exclusively tied to applications and improve the UX when clicking on an HTTP(s) link that could be opened directly in the client's application. They integrate into the native deep linking behavior, but thanks to verifying the ownership of a domain, they skip the default "Choose an application to open link" Android popup when clicking links.

Requirements

Web requirements:
The domain used for app links needs to have the Statement List file configured on the webserver to be served over HTTP or HTTPS under the .well-known slug. It needs to be returned with HTTP status code 200 without any redirects and Content-Type: application/JSON.

Application requirements:
Your app needs to add support for app links by changing the AndroidManifest.xml file, adding a new intent filter (similar to deep links), specifying the desired domain, and making sure the verification is enabled by setting autoVerify=true.

To make sure that clicks are properly tracked, you should invoke Bloomreach Engagement Android SDK's handleCampaignIntent method in the main activity (find more in the link below).

<intent-filter android:autoVerify="true">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="https" android:host="www.client.com" android:pathPrefix="/project1/" />
</intent-filter>

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.client",
    "sha256_cert_fingerprints":    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

🚧

App Links functionality is only supported on Android 6.0+ and API level 23+.
On older devices, this functionality will open the default dialog asking the user what app they want to use to open the link (i.e., browser or your app in most cases).

Links to documentation

Google - Handling Android App Links
Google - Creating a Statement List
Google - Verify Android App Links
Bloomreach Engagement Android SDK - Tracking Android App Links

Using universal links with old Mobile SDKs

The following issues on mobile devices will arise while using universal links with our old Mobile SDK (Android SDK version below 2.4.0, iOS SDK version below 2.3.0):

1. UTM attributes in session_start will not be present unless custom tracking is used
2. The campaign click event
3. The Mobile SDK will track only plain session_start

📘

Bloomreach Engagement JS SDK is updated automatically

You must update JS SDK if you keep a copy of our JS SDK stored on your web server or CDN.

Therefore, we strongly recommend to switch to our newest SDK to avoid these issues.

Tracked event

For event tracking to work properly, please note that:

• Javascript SDK must be initialized for tracking on your website,
• Mobile SDK must be properly integrated into your application (this includes calling additional methods to handle the clicks, see above),
• Your website server must allow (not remove) the Bloomreach Engagement parameter prefixed xnpe_ (read more about URL parameters used by the JS SDK).

For example, if the universal link drives traffic to a website not integrated with our SDK, no campaign click event will be tracked.

The campaign event with status=clicked should be the same when tracked from the redirect links via the cdn.exponea.com backend and when tracked from the universal links API. However, there are some known differences:

• campaign.url - When tracked from the universal links, Bloomreach Engagement does not know which UTM attributes have been added by the user and which by Bloomreach Engagement automatically. In this case, Bloomreach Engagement tracks all UTM attributes.
• campaign.user-agent - There are differences in what browser user-agent is detected by our Javascript SDK and CDN redirect backend. Universal links do not track any user agent because the user is redirected to your app.
• links are not redirected via cdn.exponea.com (potential Adblock is not blocking CTA links)

👍

The event attribute differences described above may be reflected in your reports. Campaign status=clicked events might have slightly different attributes based on their origin (CDN or universal link). Additionally, web-based clicks from universal links are filtered according to the same rules (user-agent from bots) as all JS SDK traffic. See details in
the Web tracking doc.

Using universal links

After successfully configuring your system to comply with the requirements, using the universal links feature is as easy as adding your link to your project's settings.

The following steps will get you there:

1. Go to settings by clicking on the cogwheel located in the top right corner, as highlighted in the picture.
2. Navigate to Channels > Emails.
3. At the bottom of the page, you will find the Universal Links section, where you can add your redirect links.

After you have added your redirect links, the application will then validate whether everything is set up to run smoothly and will either display a green tickbox, indicating that your link is ready to be used or a warning sign, indicating that there is some issue needing to be fixed.

🚧

Warning sign

Hovering over the warning sign will tell you what went wrong with your link. Use this to troubleshoot this either with your technicians or our online support.