HubSpot Email Service Provider (ESP) Attribution Integration

Follow
Avatar
Travis Simpson
Updated

Singular's integration with HubSpot lets you measure app installs and re-engagements with HubSpot emails that wrap your deep-link-enabled Singular Links.

While link wrapping usually breaks the deep link experience, this integration allows you to serve deep links as well as measure attributions to both installs and app opens from emails driving users into your mobile app.

The integration is based on a deep-link-enabled click tracking domain (CTD) hosted in HubSpot. When emails that include Singular Links are served to your users, HubSpot automatically wraps any Singular Link used in your email. Users who don't have the app installed will be redirected to the fallback configured in your Singular Links. Users who install the app are measured as an app install attributed to the Singular Link.

Returning users will be deep-linked into the app, where deep link handling is handled through your Singular SDK implementation. These users are measured as Re-Engagements to the Singular Link.

Prerequisites

  • Singular Links for iOS and Android
  • Singular SDKs
    • iOS SDK 11.0.0+
    • Android SDK 11.0.0+

Setup Instructions

1

Set up your email click tracking domain (CTD) in HubSpot

Follow HubSpot's documentation to configure your domain and hosting in HubSpot. 
2

Universal Link configurations for your CTD

  • Create an Apple App Site Association file for your CTD (e.g. email.mycompany.com) and add it to your website
    • If you need an example AASA file and have Singular links configured, you can check it at https://<yoursubdomain>.sng.link/apple-app-site-association
    • This file should be hosted in your website's root directory, in .well-known - e.g. https://email.mycompany.com/.well-known/apple-app-site-association
  • Upload the same AASA file in HubSpot's File Manager, per their guide here. After uploading, the AASA file should appear under Files and Folders
  • Add your domain to Associated Domains in XCode

ios-sample-app_—_ios-sample-app_xcodeproj.png

No assetlink.json file is needed for your Android path.
3

Create a Proxy Redirect in HubSpot

This enables traffic from your CTD to be redirected to the Hubspot platform to the location of your imported AASA file (from step 2). 

Follow HubSpot's Guide to set up the proxy.

Create_and_manage_URL_redirects.png

After this step, your HubSpot Email domain should open your app directly by clicking the link in the email.

The following steps enable Singular to handle the deep link and track re-engagements. 
4

Update Singular SDK Implementation

Register your CTD as an ESP domain, prior to initializing the Singular SDK. This allows the Singular SDK to recognize the custom tracking domain opening the app, allowing the Singular SDK to handle the deep link and attribution the re-engagement.

iOS:

SingularConfig* config = [[SingularConfig alloc] initWithApiKey:apiKey andSecret:secretKey];
config.espDomains = @[@"email.mydomain.com"];

Android:

SingularConfig config = new SingularConfig(apiKey, secretKey)
.withESPDomains(Arrays.asList("email.mydomain.com"));
5

Create Singular Link and add it to your HubSpot Email

Create a Singular Link for your email, using the same Singular Link subdomain (e.g... "https://<yoursubdomain>.sng.link") used in previous steps.

  • Verify that it has the proper deep link destination(s) enabled and it is configured for ReEngagement Tracking.
  • Be sure to append any reporting parameter you'd like to use for reporting via link parameters.  See all supported granularity parameters.

Place the Singular Link in your HubSpot email. When users click on this link, HubSpot will wrap this link with your CTD. In the case of a returning user clicking the link, the user will deep link into the app, and the Singular SDK will measure the app open engagement since the CTD is registered in the Singular SDK.

Notes and Tips:

  • Attributions for HubSpot emails work just like any other attributions based on Singular Links. For more information, se Singular Links and Tracking Link Parameters.
  • If your deep link is not working:
    • Ensure your custom tracking domain and destination paths are properly configured in HubSpot. This includes uploading the proper Apple App Site Association file for your app.
    • Ensure that the Singular Link embedded in your emails is also configured with deep linking. You can tell if a Singular Link has deep linking enabled if it has a _dl= parameter in the URL.