Menu
 

Setting Up Universal Links

Mobile devices are increasingly becoming the preferred method of receiving, reading, and engaging with email. If you send an email containing a link to your website, but you also have a corresponding mobile application, it is possible to ensure that any recipients who click the link on their mobile device are taken directly to your app instead of their web browsers.

This is accomplished by using universal links. A universal link is a unique URL that can be configured to open a window in either the recipient’s web browser or mobile application depending on the device the recipient is using. Customer.io enables you to use universal links in your messaging without sacrificing the ability to track clicks on those links.

Note: These links are sometimes referred to as “deep links” in the context of Google’s Android OS. Apple uses the term “universal links”.

Regardless of the OS you are configuring your links for, we will use the term “universal links”.

Requirements

There are several requirements that you must complete before you can begin using universal links in your email:

  • Universal links for iOS require an “apple-app-site-association” JSON file.
  • Universal links for Android require that you set up a “digital asset links” JSON file, along with configuring intent filters in your Android app’s manifest file.
  • Your apple-app-site-association and digital asset links files must be hosted on an HTTPS web server or content delivery network (CDN).
  • You must complete the domain verification process for your account. When whitelabeling your links, you must use the same domain that will be used for your universal links. (e.g. links.example.com)
  • On iOS, you must include your email link whitelabel subdomain in the “Associated Domains” for your app. Using the example above, you’d need to add an entry for “applinks:links.example.com” like this:

Universal Links - iOS

To keep your app secure, Google and Apple want to restrict which resources or websites are allowed to link directly to different pages within your app. This prevents bad actors from using universal links to gain access to sensitive information within your app.

Your “apple-app-site-association” and “digital asset links” files serve as secure means of authenticating your universal links; they verify that your website is allowed to open up a page within your app.

Heads up! You must create your own digital asset links and apple-app-site-association files, and you must upload these files to a secure server.

Both “apple-app-site-association” and “digital asset links” files are comprised of a series of JSON key/value pairs that associate external URLs with pages within your application.

For detailed instructions on how to configure an iOS “apple-app-site-association” file, please see Apple’s Developer Documentation.

For detailed instructions on how to configure an Android “digital asset links” file, please visit Google’s Developer Documentation.

Once you have created and configured your Android and iOS configuration files, you will have to host them on a secure HTTPS server. Keep reading below to learn how you can host these files on either Amazon CloudFront or NGINX.

After creating your iOS “apple-app-site-association” file and/or your Android “digital asset links” file, you need to host them on a secure content delivery network. The following instructions will guide you through setting up Amazon’s CloudFront to host these files.

  1. Navigate to Amazon CloudFront. Once you have created an account or are logged into your existing account, create a new S3 bucket and give it a unique name (e.g. links-example-com)

  2. Upload your “apple-app-site-association” file into the root of the new S3 bucket

  3. Under Permissions on the uploaded file, add a permission for Everyone to Open/Download (or Read in the new S3 UI), then hit Save

  4. Under Metadata on the uploaded file, change the Content-Type value to application/json, then hit Save

Universal Links - S3 Bucket

  1. Create a new folder in the bucket called “.well-known”

  2. Inside of the “.well-known” folder, upload the same “apple-app-site-association” file as in step 2

  3. As above, add a permission for Everyone to Open/Download (or Read in the new S3 UI) and change the Content-Type to “application/json”

  4. Inside of the “.well-known” folder, upload your “assetlinks.json” file

  5. Repeat step 7 for your “assetlinks.json” file: add a permission for Everyone to Open/Download (or Read in the new S3 UI) and change the Content-Type to “application/json”

  6. Navigate to the AWS Certificate Manager

  7. Request a new certificate for the domain your link whitelabel is configured for (e.g. links.example.com)

  8. AWS will send an email to the appropriate domain owners, requesting them to approve the certificate

Universal Links - AWS Certificate Manager

  1. Ensure that the certificate is approved and issued

  2. Navigate to AWS CloudFront

  3. Create a new Distribution that is a Web delivery method

  4. Under the Origin Settings section, set the fields as follows:

Universal Links - Cloudfront Origin Settings

  • Origin Domain Name: track.customer.io
  • Origin ID: track.customer.io
  • Origin SSL Protocols: only TLSv1.2
  • Origin Protocol Policy: HTTPS Only
  1. Under the Default Cache Behavior Settings section, set the fields as follows:

Universal Links - Cloudfront Cache Behavior Settings

  • Allowed HTTP Methods: GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
  • Forward Headers: All
  • Forward Query Strings: Forward all, cache based on all
  1. Under the Distribution Settings section, set the fields as follows:

Universal Links - Cloudfront Distribution Settings

  • Alternate Domain Names: links.example.com (replace with whatever your link tracking domain is)
  • SSL Certificate: Custom SSL Certificate, pointing to the appropriate ACM certificate
  1. Click Create Distribution

  2. Once the distribution is created, click into Distribution Settings

  3. Under the Origins tab, create a new origin with the following details

Universal Links - Cloudfront Origin Settings

  • Origin Domain Name: links-example-com.s3.amazonaws.com (select the S3 bucket created in step 1)
  • Origin ID: S3-links-example-com (should auto-populate)
  1. Click Create

  2. Under the Behaviors tab, create a new behavior with the following details

Universal Links - Cloudfront Behavior Settings

  • Path Pattern: apple-app-site-association
  • Origin: S3-links-example-com
  • Viewer Protocol Policy: Redirect HTTP to HTTPS
  1. Click Create

  2. Create another behavior with the following details

  • Path Pattern: .well-known/apple-app-site-association
  • Origin: S3-links-example-com
  • Viewer Protocol Policy: Redirect HTTP to HTTPS
  1. Click Create

  2. Create a third behavior with the following details

  • Path Pattern: .well-known/assetlinks.json
  • Origin: S3-links-example-com
  • Viewer Protocol Policy: Redirect HTTP to HTTPS
  1. Click Create

  2. Ensure that the Behaviors are sorted so that the Default is the last one

Universal Links - Cloudfront Behaviors

  1. Wait for the distribution to deploy

  2. Verify that the distribution serves the Customer.io API and the expected files via HTTPS. Do this using the Cloudfront Domain Name and without changing the real DNS to avoid causing any issues with existing links.

  • https://d32g0e184q3wj9.cloudfront.net/
  • https://d32g0e184q3wj9.cloudfront.net/apple-app-site-association
  • https://d32g0e184q3wj9.cloudfront.net/.well-known/apple-app-site-association
  • https://d32g0e184q3wj9.cloudfront.net/.well-known/assetlinks.json

Universal Links - Cloudfront Distribution Overview

Universal Links - Cloudfront Verification

  1. Verify behavior using https://branch.io/resources/universal-links/

  2. Once you’ve verified your Cloudfront distribution is serving the Customer.io API via HTTPS update your DNS record to change the CNAME record for links.example.com to send traffic to your Cloudfront Domain Name which is shown on the General overview tab of your Cloudfront distribution.

  • CNAME record name: links.example.com
  • CNAME record value: CHANGEME.cloudfront.net
  1. Finally back in Customer.io on your deliverability settings page select the domain you configured for HTTPS and click the Check now button to re-validate the domain. You should now pass the HTTPS check and tracking links will use HTTPS by default.

Email - Verification Status

After creating your iOS “apple-app-site-association” file and/or your Android “digital asset links” file, you need to host them on a secure content delivery network. The following instructions will guide you through setting up NGINX to host these files.

  1. Request a new certificate for the domain your link whitelabel is configured for (e.g. links.example.com)

  2. Place the certificate chain into the file named /etc/pki/tls/certs/links.example.com.crt

  3. Place the private key into the file named /etc/pki/tls/private/links.example.com.key

  4. Create the following directory /var/www/links.example.com

  5. Create the file /var/www/links.example.com/apple-app-site-association, with the appropriate content for your apple-app-site-association file, as explained in Apple’s Developer Documentation.

  6. Create the directory /var/www/links.example.com/.well-known

  7. Create the file /var/www/links.example.com/.well-known/apple-app-site-association, with the appropriate content for your apple-app-site-association file

  8. Create the file /var/www/links.example.com/.well-known/assetlinks.json, with the appropriate content for your digital asset links file, as explained in Google’s Developer Documentation.

  9. Create the file /etc/nginx/conf.d/links.example.com.conf, with the following content:

server {
  listen 80;
  listen 443 ssl;
  server_name 'links.example.com';
  ssl_certificate '/etc/pki/tls/certs/links.example.com.crt';
  ssl_certificate_key '/etc/pki/tls/private/links.example.com.key';
  location = /apple-app-site-association {
    root '/var/www/links.example.com';
    default_type 'application/json';
  }
  location = /.well-known/apple-app-site-association {
    root '/var/www/links.example.com';
    default_type 'application/json';
  }
  location = /.well-known/assetlinks.json {
    root '/var/www/links.example.com';
    default_type 'application/json';
  }
  location / {
    proxy_pass 'https://track.customer.io';
    proxy_set_header 'Host' 'links.example.com';
  }
}
  1. Update your DNS record to change the CNAME record for links.example.com to send traffic to your NGINX server. If you’re specifying the IP address of your server this will need to be an A record instead of a CNAME record.
  • A record name: links.example.com
  • A record value: IP Address of your NGINX server
  1. Finally back in Customer.io on your deliverability settings page select the domain you configured for HTTPS and click the Check now button to re-validate the domain. You should now pass the HTTPS check and tracking links will use HTTPS by default.

Email - Verification Status