Developer Guide

GTM Integration

Integrate D·engage SDK Using Google Tag Manager

If you are using Google Tag Manager (GTM) in your website, you can add D·engage Web SDK to your website by using GTM. For that, you have to create an application definition for your website on the Dengage Admin Panel.

Defining Application

In order to use D·engage Web SDK, you have to add an application for your website from the D·engage Admin Panel.

  1. Go to the “Settings”, select “Applications” from the menu.
  2. Click “Add” to add a new website.

  1. Once you have filled out the information for the website, activate “Push Notifications” in case you are going to use web push.

After saving the new website, you will be prompted with the SDK setup guide. You will see the HTML code you have to add to your website in a pop-up as shown below. This code will be used for the GTM tag configuration.

You can access this information anytime by using “See Setup Guide” from the Actions menu found in the website definition page.

Adding the D·engage SDK Tag

The HTML code you were given must be added as a tag in the Google Tag Manager.

  1. Go to the GTM workspace and click “New Tag” to add the HTML code.

  1. Give it a name like “Dengage SDK” and click “Tag Configuration”.

  1. Choose “Custom HTML” for tag type.

  1. Paste the HTML code and select “All Pages” for the trigger.

  1. Save this new tag. The D·engage SDK is added to your website. But in order to start using Web Push you have to add the service worker to your website and configure a prompt in the website definition page. For event collection see the relevant section.

Adding Service Worker (For Web Push)

In order to use Web Push, you have to add the service worker file to your website. This cannot be done with GTM.

  1. Go to website definition page and select Setup Guide.
  2. Click “Download Service Worker” to download the service worker file.
  3. Upload this file to the root directory of your website.

This file must be available in the following URL: https://yourwebsite.com/dengage-webpush-sw.js

How to Add Event Collection

In order to collect website events and use that data to create behavioral segments in D·engage you have to determine the type of events and data that needs to collected. Once you have determined that, you will need to create a “Big Data” table in D·engage. Collected events will be stored in this table. Multiple tables can be defined depending on your specific need.

Any type of event can be collected. The content and the structure of the events are completely flexible and can be changed according to unique business requirements. You will just need to define a table for events.

Once defined, all you have to do is to send the event data to these tables. D·engage SDK has only two functions for sending events: sendDeviceEvent and sendCustomEvent. Most of the time you will just need the sendDeviceEvent function.

1. Using user information
If the user loggs in or you have user information, this means you have contact_key for that user. You can set contact_key in order to match user with the browser. There are two functions for getting and setting contact_key.

dengage('setContactKey', userId);
dengage('getContactKey', function(userId) {
     //use userId (contact_key) here
});

2. Send device (browser) specific events
You can use sendDeviceEvent function for sending events for the browser. Event are sent to a big data table defined in your D·engage account. That table must have relation to the master_device table. If you set contact_key for that browser. Collected events will be associated for that user.

dengage(‘sendDeviceEvent’, tableName, dataObject [, callback]);

// for example if you have a table named "events"
// and events table has "key", "event_date", "event_name", "product_id" columns
// you just have to send the columns except "key" and "event_date", because those columns sent by the SDK

var eventData = {
  event_name: 'page_view',
  product_id: '12345'
};
dengage('sendDeviceEvent', 'events', eventData);

You can use these functions anywhere on your website code to send data. But if you want to use GTM to add these codes to your website. You can use multiple methods and this can be different for every website.

1. Using existing dataLayer events

If you have existing events in the dataLayer, you can send those events to Dengage just by using GTM. You don’t have to do any code changes on your website.

If you have tags and triggers as shown below, you can use those triggers to create tags to send data to D·engage.

For every existing event sending tag , you have to create a corresponding tag that sends data to D·engage. You will be getting the required data from variables that are defined in the tag manager. You will be using two D·engage SDK functions for creating tags: sendDeviceEvent and setContactKey.

GTM variables can be used in tags with the double curly braces syntax. If you have a variable called “product id” you can use this value in your tags as {{ product id }}.

  • Login / Logout Events

For a user login event, you must add a tag that gives the user id to the Dengage SDK. A user id is called a contact key in Dengage platform. For this action use the setContactKey function.

dengage(‘setContactKey’, {{ user id }});

Also, when a user logs out you can empty this value. This is optional.

dengage(‘setContactKey’, ‘’);
  • Other Events

Events other than login/logout can be sent using the sendDeviceEvent function.

For example if you have a transaction event and some variables related to this event like transactionId, transactionTotal, transactionTax, transactionShipping, you will be using a code as shown below:

dengage('sendDeviceEvent', ‘user_events’, {
    transaction_id: {{ transactionId }},
    transaction_total: {{ transactionTotal }},
    transaction_tax: {{ transactionTax }},
    transaction_shipping: {{ transactionShipping }}
});

Please note that the ‘user_events’ part is the table name that you have created as Big Data Table the D·engage Admin Panel.

2. Add D·engage Data to dataLayer

This method requires code changes in your website. Use this method If you previously have no data or events added to the dataLayer or you don’t want to use existing data.

If you want to use the dataLayer to send data to D·engage, you have to push relevant data to the dataLayer where that event has happened. You can give these events a common name like dengage_event and add a trigger in GTM.

Use a code as shown below where necessary:

dataLayer.push({
    event: ‘dengage_event’,
    dengage_table_name: ‘events’,
    dengage_event_data: {
        var1: ‘aaa’,
        var2: ‘bbb’,
    },
});

This added data will not be sent automatically to D·engage. In order to do that you have to add a tag in GTM. This tag requires two variables and a trigger.

  1. First go to the “Variables” menu and click “New”.

  1. Give it a name like “Dengage event data” then choose “Data Layer Variable” as variable type.

  1. Enter “‘dengage_event_data’” as variable name.

  1. Create another variable called “Dengage table name” using same steps. Use “dengage_table_name” as variable name. Result must be seen as shown below:

Once you have created variables, you will need to create a trigger for D·engage events.

  1. Select “Triggers” from the menu and click “New”.
  2. Give “Dengage event” as the name and choose “Custom event” as trigger type.

  1. Enter “dengage_event” as the event name.

  1. Go to “Tags” menu and click “New”.
  2. Give it a name like “Send dengage event” and select “Custom HTML” as tag type.

  1. Paste the code below and select “Dengage event” as trigger type.

Result must be seen as shown below:

After that you can test this workspace and Publish.