dEngage Web SDK Setup

Requirements

  • dEngage Application Definition
  • Access to your website files

dEngage Web SDK provides an interface which handles web push notifications. Optionally, It also provides event tracking functionality for your website.

1. Create dEngage Application

In order to use web SDK you have to create a push application definition in dEngage platform and add necessary files and code to your website.

1.1 Go to dEngage adminpanel and settings page. Then, go to Applications and click Add a new web site.

1.2 Enter website and default logo url then set push notifications enabled.

1.3 Select how to prompt web push permission. You can change how the prompt will look like.

If you select “Show Prompt Automatically”, permission prompt will be shown automatically.

2. Update your website code

After you created push application in dEngage admin panel. Your website integration information will be shown like below.

You have to download service worker file and put it in your website’s root folder. After that you have to insert given code snippet into your website’s HTML code. If you selected “Show Prompt Automatically”, web push integration will work automatically. But you can trigger notification prompt manually by SDK functions.

3. Usage of Web SDK

When you insert Web SDK code into your main HTML file, the main functionality of the SDK will start automatically. This includes showing notification permission prompt and tracking subscription. So the initialization function is important.

<script type="text/javascript">
…….
dengage(‘initialize’);
</script>

3.1 Triggering Notification Prompt Manually

If you want to trigger notification prompt manually. You can use showNativePrompt or showCustomPrompt functions. showNativePrompt shows browser’s native prompt immedietely. showCustomPrompt shows the prompt you have selected in your application settings. For example slide or banner. But native prompt will be shown after user accepted.

dengage(‘showCustomPrompt’); //for showing selected prompt in app settings
dengage(‘showNativePrompt’); //for showing native prompt

If you have a button or banner for getting notification permission you can use showNativePrompt in click handler of that button or banner.

3.2 Getting notification permission

You can use getNotificationPermission function for getting user’s current notification permission. This function returns a string value that can be ‘granted’, ‘denied’ or ‘default’.

dengage(‘getNotificationPermission’, function(permission) {
    if (permission == ‘granted’) {
       //permission granted
    } else {
       //permission not granted
    }
});

3.3 Getting current token

For getting current push token, use getToken function. If push permission is not granted, this function returns null.

dengage(‘getToken’, function(token) {
    if (token == null) {
       //token is not available
    } else {
       //we have token
    }
});

3.4 Check push support for browser

If you want to learn whether the browser supports Push notifications or not, use isPushNotificationsSupported function. This function return true if it is supported.

dengage(‘isPushNotificationsSupported’, function(isSupported) {
    if (isSupported) {
       //push notification is supported
		    } else {
       //push notification is not supported
    }
});

3.5 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
});

3.6 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 dEngage 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);

3.7 Send custom events

If you want to send events to a table that is not related to master_device, you can use sendCustomEvent function. This function is similar to sendDeviceEvent, but extra you have to send a key for the event. The key can be anything. For example contact_key can be used as key.

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

var contact_key = 'user_123456';
var eventData = {
  action: '...',
  data1: '...',
	...
};
dengage(‘sendCustomEvent’, ‘user_actions’, contact_key, eventData);