This documentation shows how you can use the Countly GTM SDK in Google Tag Manager platform.

You can reach the source code of the SDK from its Git repo here.

Adding the SDK to the Project

You can reach the Countly SDK template in your Google Tag Manager container through:

Workspace > Tags > New > Tag Configuration > Community Template Gallery > Countly Analytics

Another method to get the SDK template is to add it manually after downloading it from the Git repo here. You can either download it as a zip file and extract its content:

Code > Download ZIP 

or you can clone the repo and reach files directly:

git clone https://github.com/Countly/countly-sdk-gtm.git

After you should import the template.tpl file you have downloaded to your container through:

Workspace > Templates > New > Import

Now it should be available at:

Workspace > Tags > New > Tag Configuration > Countly Analytics

SDK Integration

The template exposes its functionality through the Action Selection drop down. Four actions are available: Initialize the SDK, Record Event, Display Feedback Widget and Refresh Content Zone. Each action reveals its own set of fields once selected.

Minimal Setup

The first thing you should be doing with the SDK template is to initialize the SDK as soon as possible on your web page by selecting a proper trigger. Initialization trigger is a good candidate for this. For SDK initialization the template offers the action Initialize the SDK in the drop down menu:

Here the Server URL and the App Key are mandatory values. Please check here for more information on how to acquire your application key (APP_KEY) and server URL.

Enabling Features

After setting up you App Key and Server URL you will see checkboxes below. These are optional features of the SDK that you can enable during initialization:

• Enable SDK Logs: Enables the SDK to print logs in browser console for debugging 
• Track Sessions: Enables automatic session tracking
• Track Page Views: Enables automatic view tracking
• Track Clicks: Enables automatic tracking of user click actions
• Track Scrolls: Enables automatic tracking of user scroll actions
• Track Errors: Enables the tracking of JavaScript errors happening on your website
• Track Links: Enables automatic tracking of link clicks on your website
• Enabled Journeys: Enables Countly Content (Journeys) by entering the content zone after initialization, so that eligible content can be delivered to your users

Server Configuration

Starting with version 25.4.0, the SDK has the Server Configuration feature enabled, and it is turned on by default. Changes you make under SDK Manager > SDK Configuration on your Countly server can directly affect the behavior of the SDK, so keep in mind that server-side configuration may override the options you set here.

Events

Another action the SDK template provides is the ability to record events. Events are a way to track any custom actions or other data you would like to track from your website. You may also set segments to be able to view a breakdown of the action by providing the segment values.

To record an event you would need to use the Record Event action in the template's drop down menu:

Here the Event Key is a mandatory value. It represents the name of the event that you will see in your Countly server. The remaining fields are optional:

• Event Sum: A numeric value that is summed across all occurrences of the event (for example, a purchase amount).
• Event Duration: A non-negative numeric value representing how long the event took, in seconds.
• Event Count: A positive whole number for how many times the event occurred.
• Segmentation: Optional key/value pairs sent with the event so you can view a breakdown of the action by the provided segment values.

Feedback Widgets

It is possible to display 3 kinds of feedback widgets: NPS, Survey, and Rating.

For more detailed information about Feedback Widgets, you can refer to here.

To show a widget, select the Display Feedback Widget action from the drop down menu. From the Select Widget drop down you can choose the type of widget to display:

• Survey: Displays a Survey widget.
• NPS: Displays a Net Promoter Score (NPS) widget.
• Rating: Displays a Rating widget.

You may optionally fill in the Optional Widget Name, Tag or ID field to display a specific widget. If it is left empty, the first available widget of the selected type that matches your targeting rules will be shown.

Content & Journeys

The Content Zone feature enhances user engagement by delivering various types of content blocks, such as in-app messaging, ads, or user engagement prompts by utilizing Journeys. These content blocks are dynamically served from the content builder on the server, ensuring that users receive relevant and up-to-date information.

The template interacts with Content in two ways:

• Enabling on initialization: Tick the Enabled Journeys checkbox in the Initialize the SDK action. This makes the SDK enter the content zone after initialization: it retrieves and displays any available content for the user, then regularly checks whether new content has become available and fetches and shows it when it has.
• Refreshing content: Use the Refresh Content Zone action to manually refresh the content zone and check for new content immediately. This is useful when you want to trigger a Journey and display its content right after a specific user action, rather than waiting for the next automatic check. This action does not require any additional fields.