[NEW] Singular Website SDK: Google Tag Manager Integration

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.

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 that 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 window loaded).

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:
    • API Key: Your Singular SDK API key, e.g. “example_api_key1”.
    • Secret: Your Singular SDK secret, e.g. “ff3bfbce70b42a70fe920f42737d2123”.
    • Product Id: A name for your website. We recommend using reverse DNS notation, e.g. “com.example.site”. This will be used to identify your website throughout the Singular platform.
  5. Click Triggering and add the trigger “Window Loaded”.
  6. Click Save.

image6.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

Singular can collect data about user events within the site to help analyze the performance of your campaigns 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

Was this article helpful?
0 out of 0 found this helpful