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.