Singular Website SDK: Google Tag Manager Integration

Follow
Avatar
Eyal Rabinovich
Updated

The Singular Website SDK is an enterprise feature. If you're interested in using this feature, reach out to your Customer Success Manager.

Singular Website SDK (GTM Integration)
Browser Compatibility
  • Chrome: 15+                       
  • Safari: 5.1+
  • Edge: 15+
  • Firefox: 6+       
  • Internet Explorer: 10+            
  • Opera: 15+

 

Introduction

The Singular Website SDK allows you to attribute website activities to marketing touchpoints and to track user events within your website. It is also a key component in Singular’s cross-device attribution solution, making it possible to analyze user journeys and calculate cross-platform LTV and ROAS. For your convenience, the Singular Website SDK is integrated with Google Tag Manager.

See also: Integrating the Singular Website SDK without Google Tag Manager

Prerequisites

Before you integrate the Singular Website SDK, make sure that:

  • Google Tag Manager has been configured on your site.
  • You have set up Google Tag Manager triggers as needed for the events that you want to send to Singular (your conversion event and any custom events). See About Triggers in the Google documentation.
  • You have set up Google Tag Manager variables as needed for the events you want to send to Singular. For example, if you want to send transaction events and include the transaction revenue, you need to set up variables for the transaction sum and currency. See About Variables in the Google documentation.

Integrating the Singular SDK

Initializing the SDK

To use the Singular Web SDK in your website, you must add the Singular initialization tag. We recommend setting this event to be triggered as soon as your website loads (e.g., on page view).

To add a Singular initialization tag:

  1. In your Google Tag Manager account, click Tags > New.
  2. In the Tag Configuration window, click Tag Configuration, and in the Tag Type menu, select “Singular Web Tracking”.
  3. Under Track Type, select “Initialization”.
  4. Fill in the other required parameters:
    • SDK Key and SDK Secret: You can retrieve these by logging into your Singular account and going to "Developer Tools > SDK Integration > SDK Keys".
    • Product Id: A name for your website. We recommend using the reverse DNS notation of your main web domain, e.g., “com.example”. This will be used to identify your website throughout the Singular platform. This value must also match the App bundleID on the Apps Page in the Singular platform.
    • Optional:
      • Log Level: The configuration of SDK debug logging to console. The default is none.
      • Session Timeout: How long the user has to be inactive before the SDK creates a new session. Singular sends user sessions to calculate user retention and enable re-engagement attribution. The default value is 30 minutes.
      • Cross Sub-Domain Tracking
  5. Click Triggering and add the trigger “Page View”.
  6. Click Save.

mceclip0.png

Note:  For SPAs (Single Page Applications), you should trigger the PageVisit trackType every time you route to a different page. Do not call PageVisit on the first page that is loaded since Initialization already reports a page visit.

image5.png

Optional: Setting the User ID

As long as the user performs actions on your website without being logged in, events are sent to Singular with a Singular-generated user ID. But after the user registers or logs in, you can have events sent to Singular along with the user ID that is used on your website, e.g., an email address.

Singular uses the user ID in user-level data exports (see Exporting Attribution Logs) as well as internal BI postbacks, if you have them configured (see Configuring Internal BI Postbacks).

There are two ways to send the user ID to Singular:

  • Recommended: If you know the user ID when the website opens, set the user ID in the Initialization track type when initializing the SDK. This makes the user ID available to Singular from the very first page visit.
  • Alternatively, you can call the Login method at any point in the run. We recommend calling it as soon as the user ID becomes available.

To share the user ID with Singular, add a Singular tag with the “Login” track type:

  1. In your Google Tag Manager account, click Tags > New.
  2. In the Tag Configuration window, click Tag Configuration, and in the Tag Type menu, select “Singular Web Tracking”.
  3. Under Track Type, select “Login”.
  4. Under Custom User Id, enter the Google Tag Manager variable that contains the user ID.
  5. Click Triggering and add the triggering event: user login or registration.
  6. Click Save.

image4.png

To unset the user ID, add a tag with the “Logout” track type:

  1. In your Google Tag Manager account, click Tags > New.
  2. In the Tag Configuration window, click Tag Configuration, and in the Tag Type menu, select “Singular Web Tracking”.
  3. Under Track Type, select “Logout”.
  4. Click Triggering and add the triggering event: user logout.
  5. Click Save.

image1.png

Notes: 

  • The user ID persists until you unset it using the logout track type or until the user deletes their local storage.
  • Closing/refreshing the website does not unset the user ID.
  • Browsing in private mode such as incognito will prevent Singular from persisting the user ID, because the local storage is deleted automatically when closing the browser.

Optional: Tracking Events and Revenue

Tracking Events (Non Revenue)

Singular can collect data about user events within the site to help analyze your campaigns' performance and measure KPIs. For example, your organization may want to collect data about user logins, registrations, or tutorial completions.

You can send events to Singular using the event method.

Notes:

  • We highly recommend passing event names and attributes in English to guarantee compatibility with third-party partners and analytics solutions if you plan to use them.
  • Event names are limited to 32 ASCII characters. Strings in non-ASCII characters have to be under 32 bytes once converted to UTF-8.
  • Attributes and values are limited to 500 ASCII characters.

To track a custom event:

  1. In your Google Tag Manager account, click Tags > New.
  2. In the Tag Configuration window, click Tag Configuration, and in the Tag Type menu, select “Singular Web Tracking”.
  3. Under Track Type, select “Custom Event”.
  4. Under Event Name, enter a name for the event or enter a Google Tag Manager variable that you have defined previously.
  5. Click Triggering and add the triggering event.
  6. Click Save.

image3.png

Tracking Revenue    

Singular can collect data about revenue gained through the website to help analyze the performance and ROI of your campaigns. Singular will make the data available to you in reports, log exports, and postbacks.

Use the revenue method to report events. Revenue allows you to pass a custom event name so that you'll be able to view revenue in Singular reports broken down by the different types of revenue events.

Notes: Any revenue reported in a different currency will be auto-converted to your organization's preferred currency, as set in your Singular account.

To track revenue events:

  1. In your Google Tag Manager account, click Tags > New.
  2. In the Tag Configuration window, click Tag Configuration, and in the Tag Type menu, select “Singular Web Tracking”.
  3. Under Track Type, select “Revenue Event”.
  4. Under Event Name, enter a name for the event or enter a Google Tag Manager variable that you have defined previously.
  5. Under Currency, enter a variable that represents a three-letter ISO 4217 currency code, such as  “USD”, “EUR”, or “INR".
  6. Under Revenue, enter a variable that contains the transaction amount (can be passed as a decimal value, e.g., 1.99).
  7. Click Triggering and add the triggering event.
  8. Click Save.

image2.png

Optional: Cross Sub-Domain Tracking

By default, the Singular Website SDK generates a Singular Device ID and persists it using browser storage. Since this storage can't be shared between subdomains, the SDK ends up generating a new ID for each subdomain.

If you want to persist the Singular Device ID across subdomains, you can use one of the following options:

Method A: Auto-Persist using Cookies

You can have the Singular SDK persist the Singular Device ID using a custom first-party cookie. Choose the following option and set the main domain you want to track.

mceclip1.png

Method B (Advanced): Read Singular Device ID for GTM variable

If you don’t want Singular SDK to persist the Device ID automatically, you can persist the ID manually across domains - for example, using a top-level domain cookie or a server-side cookie. The value should be an ID previously generated by Singular in valid uuid4 format.

Note: You can read the Singular Device ID by defining a custom JavaScript variable and calling singularSdk.getSingularDeviceId() after calling the Init track-type tag.

mceclip2.png

Custom User Id Device Mapping

Important: This is an advanced feature. Consult with one of Singular’s Solution Engineers before implementing.

Singular can receive additional web tracking data via server to server integration. To utilize this feature, we need to map the custom user id to Singular’s web tracking identifier.

Note: Call this track type as soon as possible after initializing the SDK or once you have the custom user id.

To map Custom User Id to Singular’s web tracking identifier:

  1. In your Google Tag Manager account, click Tags > New.
  2. In the Tag Configuration window, click Tag Configuration, and in the Tag Type menu, select “Singular Web Tracking”.
  3. Under Track Type, select “Set Device Custom User Id”.
  4. Under Custom User Id, enter the Google Tag Manager variable that contains the user ID.
  5. Click Triggering and add the triggering event.
  6. Click Save.

Screen_Shot_2020-04-13_at_18.14.29.png

Optional: Match ID

Important: This is an advanced feature. Consult with one of Singular’s Solution Engineers before implementing it.

Singular can attribute server to server installs from PC & Console platforms based on a deterministic unique Match ID per user. In order to utilize this feature, either retrieve the Singular generated Match ID from Singular's Web SDK after initialization, or set the Match ID to your own value.

Set Match ID

Sets a custom Match ID for this web session. This tag should be triggered as soon as your Match ID becomes available. Triggering this tag with a new Match ID will update the previously set Match ID to the new Match ID. 

Google_Tag_Manager.png

Clear Match ID

Clears custom Match Id set from the Set Match ID tag, and updates Match ID to default value. This tag should be triggered when the previously set Match ID is no longer relevant 

Google_Tag_Manager.png