Deep Linking Functionality

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.

Deep Links are available for both iOS and Android, 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. Decode the full URL to direct your recipient to
  4. POST back the click activity to MessageGears for click recording

MessageGears deep linking feature supports both iOS Universal Links as well as Android Deep Links.

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.

To enable deep links, you will need to send your customer support representative 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. Consider:

    <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 creatte 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. Once you’ve contacted support and have upgraded your account to deep links, you are ready to begin utilizing deep linking functionality.

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 your 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 decode and handle the mg_x_url in your link.

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:

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. Ignoring the recipient token for now (we’ll get to that later), to understand where the actual end destination is I isolate the param after mg_x_url:

aHR0cHM6Ly9tZXNzYWdlZ2VhcnMuY29tL2Jsb2cvaW1wcm92aW5nLXRoZS1jdXN0b21lci1leHBlcmllbmNlLXdpdGgtZGVlcC1saW5raW5nP0V4YW1wbGU9VHJ1ZQ%3D%3D

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

aHR0cHM6Ly9tZXNzYWdlZ2VhcnMuY29tL2Jsb2cvaW1wcm92aW5nLXRoZS1jdXN0b21lci1leHBlcmllbmNlLXdpdGgtZGVlcC1saW5raW5nP0V4YW1wbGU9VHJ1ZQ==

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

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

This provides me with the intended destination from above to which my application should redirect my recipient. However, since the click was not redirected through MessageGears’ click tracking servers, your MessageGears reporting will not have this click accounted for. This brings us to our final step in the process.

4) POSTing Click Activity to MessageGears

Thus far, we have created deep linking files so that 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, we will use our 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, we will be isolating 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. We 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"
}'

See our Click Tracking Documentation for more information on POSTing clicks to MessageGears.