170

Track universal links and app links in email

Deep links take users to content inside your app. Apple’s universal links are one type of deep link. Android’s app links are another. With universal links and app links, you provide a standard web link and fallback should a user not have your app downloaded. To track them in Customer.io, you must add a special liquid tag, explained below. This article discusses how to set up universal and app links to direct email recipients to a page in your mobile app and track clicks on these links.

Set up universal and app links in email

Follow the steps in our SDK docs to set up universal links for iOS, linked above. Follow the steps for Google’s documentation to set up app links for Android.

Track universal and app links in email

Customer.io wraps tracked links in a URL that points to a domain we control and can use to log your clicks. Once logged, we then redirect people to the URL you originally used for the link. This poses a problem for universal links and app links, however, because your tracked links no longer point to a path you have configured in your app site configuration files.

To address this, we created a special liquid tag you can add to your universal and app links—{% cio_link_id %}.

To log clicks on your universal and app links within Customer.io emails, you have to:

1. configure all universal and app links as untracked in our system, then
2. pass the clicked links to us programmatically for tracking

1. Configure universal and app links as untracked

Per your app site configuration files for iOS and Android, you must format any link that takes users to content inside your app like the link shown in the image below.

The link must contain these two components:

1. link_id={% cio_link_id %} This gives us a way to send you the link id as a query parameter value so that you can pass the link to us for tracking. We’ve used cio_link_id in this example, but the parameter name can be anything your system will recognize as the link id token you need to send back to us.
2. class="untracked" This ensures that we don’t wrap this link like we do for conventional links. You may add other classes, if needed, but you must include untracked to ensure that we don’t alter the link.

After you send your email, universal and app links point to a URL that looks something like: http://yourwebsite.com/confirm/?link_id=eyJlbWFpbF...928bf

(Note, we’ve truncated the link id token in the example because it is normally quite long.)

2. Pass universal and app links for tracking purposes

Next, from within your app, retrieve the link_id token from the request URL. Pass it to Customer.io by sending a POST request from within your app to a URL that will look something like this one:

• https://<your-tracking-domain>/click/<link_id>

  • Replace <link_id> with the value pulled from the link_id parameter.
  • Replace <your-tracking-domain> with the sending domain you use in your workspace’s deliverability settings.

You can locate your deliverability settings by going to Workspace Settings > Email > Manage Domain > Link Tracking. Then click the Configure button on the line for the message’s sending domain (i.e. the domain used in the FROM address of your message).

If you configured a CNAME record in your domain’s DNS records as your custom link tracking domain in Customer.io, then you need to replace <your-tracking-domain> above with that domain. For example, if the custom link tracking domain in your settings says email.yourdomain.com AND we have verified your CNAME record for that domain, then you would perform an HTTP POST to URLs that are formatted like: http://email.yourdomain.com/click/eyJlbWFpbF...928bf so that we can log the click.

If we have NOT verified your CNAME record for the sending domain, then you will replace <your-tracking-domain> above with e.customeriomail.com instead so that we can log the click.

Note that the tracking domain you send this to must match the domain you configured in your deliverability settings discussed above. Each of our link ids are cryptographically signed by Customer.io using your tracking domain for security purposes, so the request must arrive on the same domain for validation.

Reporting on universal and app links

Assuming the token we receive is valid, we will respond with a 200 OK response and register a click for the associated message. You will see this in your account as a “Clicked Email” event in your activity log. There, the href value will contain (CIO--LINKID) instead of the long value, which indicates it was a universal or app link.

You can also look at the “Top Clicked Links” section found on the relevant campaign’s Overview tab.

FAQs

Deep links vs. universal and app links

Deep links refer to any link that sends a user deeper into your app. Universal links are one type of deep link created by Apple, starting in iOS 9. App links are Android’s version. Historically, URI schemes enabled you to direct users to content within an app with links like myapp://profile/33138223345, which is still a viable option. Universal links and app links, however, allow you to direct users to content within an app using regular web links like https://yourdomain.com/profile/content. They also let you set a fallback destination if the user has not installed your app, unlike URI schemes. The lack of a fallback for URI schemes makes it very difficult to ensure that your URI scheme will always open deep links in the app and manner you expect them too.

Do not use {% cio_link_id %} in other tracked links

We don’t support the use of {% cio_link_id %} inside non-universal, tracked links because it causes a circular dependency, where in order to generate the link_id we need to know the full value of the link, but in order to know the full value of the link we need to generate the link_id.