Articles in this section

Deep Linking Functionality

Jason Piraino
Updated

Overview

MessageGears Deep Linking functionality is a powerful and flexible ways to send users to your application without the need for an embedded SDK within your app.

MessageGears deep linking feature supports both iOS Universal Links as well as Android Deep Links, with a simple 4-step workflow:

  1. Configuring your Assetlinks/AASA files on your MessageGears tracking domain
  2. Creating ‘Deep Links’ in your messages
  3. Handling wrapped deep links in your iOS and/or Android Apps

  4. POSTing Click Activity to MessageGears

Table of Contents

1) Configuring Your Application and Setting Up Deep Linking Files

2) Creating Deep Links

3) Handling Deep Links Within Your Application

Method 1 - GET Redirect Location

Method 2 - Decode and POST

4) POSTing Click Activity to MessageGears

Process

Before you can start enabling deep link functionality for your application through MessageGears, you must enable secure link tracking for your application. If you’d like to enable secure or universal link tracking for your account, please Contact Support.

1) Configuring Your Application and Setting Up Deep Linking Files

Along with enabling associated domains in your application, the first step in creating deep link functionality is to allow MessageGears to host your necessary application information on your MessageGears-hosted tracking domain. As outlined in the developer documentation provided by iOS and Android, the deep linking file hosted on your tracking domain allows for links sent on your tracking domain to be recognized by your application.  This file is automatically and dynamically generated based on the below details that MessageGears Support will request during the setup process - there won't be a need to manually upload or update a file.

To enable deep links, you will need to send MessageGears Support the following information:

  • iOS applications: Your iOS app ID
  • Android Applications: Your app’s namespace, package name, and SHA fingerprint

After setting up and provisioning your deep link files, your tracking domain will serve the following AASA/Assetlinks files:

AASA:

{
  "applinks" : {
    "apps" : [ ],
    "details" : [ {
      "paths" : [ "/c/m/*", "/c/ma/*" ],
      "appID" : "<your_ios_app_id>"
    } ]
  }
}

These patterns match the deep link patterns our application creates, allowing all deep links to be routed to your application.

Assetlinks:

[ {
  "relation" : [ "delegate_permission/common.handle_all_urls" ],
  "target" : {
    "namespace" : "android_app",
    "package_name" : "<your_package_name>",
    "sha256_cert_fingerprints" : [ "<your_fingerprints>" ]
  }
} ]

2) Creating Deep Links

After setting up your deep linking files on your MessageGears tracking domain, you are now ready to create and track deep links.

The typical MessageGears link tracking process augments your links with tracking details that help to track click activity for reporting purposes. The typical tracked link format is:

http://www.{tracking_domain}/c/4/{click_codec}

Any Clicks are then relayed through MessageGears’ click tracking servers before relaying the recipient to their intended destination.

To create a deep link, simply set the mobile parameter on a URL to be true in your HTML. For example:

<body>
 <h1>MessageGears</h1>
 <p>Reliable Message Delivery</p>
 <p>Be sure to visit <a href="https://messagegears.com/blog/improving-the-customer-experience-with-deep-linking?Example=True" mobile="true">www.messagegears.com</a> for more information.</p>
</body>

The above HTML snippet would create a mobile link within your message. MessageGears deep links are formatted differently, making it possible for your application to find the intended destination of a link while still sending the link with your brand’s tracking domain. These links take the format of:

https://www.{tracking_domain}/c/m/?T={recipient_token}&mg_x_url={encoded_url}

This pattern allows for MessageGears to track any clicks by any device that has not downloaded a deep linking file while also conforming to the pattern downloaded by the recipient’s device.

Alternatively, deep link tracking can be enabled at the account level with a request to MessageGears Support, which will force all links sent from the account to be deep links.  In this scenario, the mobile="true" parameter is not required to create deep links.  Instead, you can disable deep link tracking on a per-link basis by setting mobile="false".

For example, an account with deep link tracking enabled can use the following code to override the setting and send a standard tracking link:

<body>
 <h1>MessageGears</h1>
 <p>Reliable Message Delivery</p>
 <p>Be sure to visit <a href="https://messagegears.com/blog/improving-the-customer-experience-with-deep-linking?Example=True" mobile="false">www.messagegears.com</a> for more information.</p>
</body>

3) Handling Deep Links Within Your Application

After setting up your deep linking files and enabling the ability to create deep links in your mailings, it’s necessary for your application to be able to handle the deep links that it opens.

By default, once recipients have upgraded their applications and have saved the new deep linking files to their mobile devices, any links sent out with that tracking domain will redirect to your application. This is convenient as it preserves your brand across all mailings, but it also means that the links your recipients will open do not have the intended destination in clear text. Therefore your application will need to get to the final destination in one of two ways:

  1. Decode mg_x_url to get the final app destination. POST to MG Click API.
  2. GET request on wrapped tracking URL to receive 302 Found - Location Header.

As an example, consider this HTML snippet:

<body>
 <h1>MessageGears</h1>
 <p>Reliable Message Delivery</p>
 <p>Be sure to visit <a href="https://messagegears.com/blog/improving-the-customer-experience-with-deep-linking?Example=True" mobile="true">www.messagegears.com</a> for more information.</p>
</body>

The rendered deep link from this content would yield the wrapped link:

http://track.messagegears.com/c/m/?T=1%3AMjMyOTUyMjg%3AZDAtdDE5MDk4LTJiMGZjMTlkNzk5MDQzMGY5NDg0ZGVlYTU2MzI1ODFi%3Abmljay56aWVjaEBtZXNzYWdlZ2VhcnMuY29t%3An%3AMA%3A%3AVDaaOtdwQcbpESueEUXW6g&mg_x_url=aHR0cHM6Ly9tZXNzYWdlZ2VhcnMuY29tL2Jsb2cvaW1wcm92aW5nLXRoZS1jdXN0b21lci1leHBlcmllbmNlLXdpdGgtZGVlcC1saW5raW5nP0V4YW1wbGU9VHJ1ZQ%3D%3D&m=false

By default, this link will be redirected to my application.

Method 1 - GET Redirect Location

Your app will need to intercept this link to run a GET request:

GET http://track.messagegears.com/c/m/?T=1%3AMjMyOTUyMjg%3AZDAtdDE5MDk4LTJiMGZjMTlkNzk5MDQzMGY5NDg0ZGVlYTU2MzI1ODFi%3Abmljay56aWVjaEBtZXNzYWdlZ2VhcnMuY29t%3An%3AMA%3A%3AVDaaOtdwQcbpESueEUXW6g&mg_x_url=aHR0cHM6Ly9tZXNzYWdlZ2VhcnMuY29tL2Jsb2cvaW1wcm92aW5nLXRoZS1jdXN0b21lci1leHBlcmllbmNlLXdpdGgtZGVlcC1saW5raW5nP0V4YW1wbGU9VHJ1ZQ%3D%3D&m=false

The response will be a 302 Found with a Location Header:

HTTP/1.1 302 Found
cache-control: no-cache max-age=0
content-length: 0
location: https://messagegears.com/blog/improving-the-customer-experience-with-deep-linking?Example=True
date: Mon, 30 Aug 2021 17:31:42 GMT

The location above is the final destination for your app. The GET request will also automatically record the click for analytics.

Alternatively, you can use Method 2 to decode the wrapped link first.

Method 2 - Decode and POST

Ignoring the recipient token for now (we’ll get to that later), to understand where the actual end destination is isolate the param after mg_x_url:

aHR0cHM6Ly9tZXNzYWdlZ2VhcnMuY29tL2Jsb2cvaW1wcm92aW5nLXRoZS1jdXN0b21lci1leHBlcmllbmNlLXdpdGgtZGVlcC1saW5raW5nP0V4YW1wbGU9VHJ1ZQ%3D%3D

Then URL Decode this value to get our non-URL safe version:

aHR0cHM6Ly9tZXNzYWdlZ2VhcnMuY29tL2Jsb2cvaW1wcm92aW5nLXRoZS1jdXN0b21lci1leHBlcmllbmNlLXdpdGgtZGVlcC1saW5raW5nP0V4YW1wbGU9VHJ1ZQ==

And then Base 64 Decode to reveal the URL-encoded string:

https://messagegears.com/blog/improving-the-customer-experience-with-deep-linking?Example=True

This should provide you with the intended destination from above to which your application should redirect the recipient. However, since the click was not redirected through MessageGears’ click tracking servers, MessageGears reporting will not have this click accounted for. 

4) POSTing Click Activity to MessageGears

At this point in the process, deep linking files have been created so that the deep links are opened in the application, rendered deep links, and handled them in the app. In this step, we post the recipient information back to MessageGears to record this click in my recipient activity.

For this example, use the previous link generated above:

http://track.messagegears.com/c/m/?T=1%3AMjMyOTUyMjg%3AZDAtdDE5MDk4LTJiMGZjMTlkNzk5MDQzMGY5NDg0ZGVlYTU2MzI1ODFi%3Abmljay56aWVjaEBtZXNzYWdlZ2VhcnMuY29t%3An%3AMA%3A%3AVDaaOtdwQcbpESueEUXW6g&mg_x_url=aHR0cHM6Ly9tZXNzYWdlZ2VhcnMuY29tL2Jsb2cvaW1wcm92aW5nLXRoZS1jdXN0b21lci1leHBlcmllbmNlLXdpdGgtZGVlcC1saW5raW5nP0V4YW1wbGU9VHJ1ZQ%3D%3D&m=false

For this part, you will need to isolate the unique recipient token in the first query parameter:

1%3AMjMyOTUyMjg%3AZDAtdDE5MDk4LTJiMGZjMTlkNzk5MDQzMGY5NDg0ZGVlYTU2MzI1ODFi%3Abmljay56aWVjaEBtZXNzYWdlZ2VhcnMuY29t%3An%3AMA%3A%3AVDaaOtdwQcbpESueEUXW6g

This value contains all of the encoded information that MessageGears needs to uniquely identify a recipient click. You want to POST this information back to MessageGears (URL Decoded) with any additional information we know about the recipient - here is an example cURL command:

curl -X POST \
  https://api.messagegears.net/cb/click \
  -H 'Content-Type: application/json' \
  -d '{
  "remoteIp": "8.8.8.8",
  "destination": "aHR0cHM6Ly9tZXNzYWdlZ2VhcnMuY29tL2Jsb2cvaW1wcm92aW5nLXRoZS1jdXN0b21lci1leHBlcmllbmNlLXdpdGgtZGVlcC1saW5raW5nP0V4YW1wbGU9VHJ1ZQ==",
  "userAgent": "Mozilla/5.0 (BlackBerry; U; BlackBerry 9900; en) AppleWebKit/534.11+ (KHTML, like Gecko) Version/7.1.0.346 Mobile Safari/534.11+",
  "token": "1:MjMyOTUyMjg:ZDAtdDE5MDk4LTJiMGZjMTlkNzk5MDQzMGY5NDg0ZGVlYTU2MzI1ODFi:bmljay56aWVjaEBtZXNzYWdlZ2VhcnMuY29t:n:MA::VDaaOtdwQcbpESueEUXW6g"
}'
Was this article helpful?
1 out of 1 found this helpful

Comments

0 comments

Please sign in to leave a comment.