Requirements
- D·engage Application Definition - Required for configuring push notification settings.
- Access to your Website Files - Needed to add the Service Worker File and the Injection Script.
D·engage Web SDK provides an interface that handles device subscriptions and web push notifications. Optionally, it also provides event tracking functionality for your website.
1. Creating the D·engage Application
To use the Web SDK, create an application and set up push notification configuration in the D·engage platform, then add the Service Worker File and the Injection Script to your website.
1.1 Navigate to Settings > Applications. Click New to create a new application.

Applications
1.2 Select Website from the modal that appears.

Website
1.3 Enter the application name, website domain URL and icon or badge URL.

Website Application
1.4 Enable the Push Notifications.

Push Notifications - Enabled
1.5 Select the Custom Permission Prompt type. Open Settings to customize it.

If you enable the “Show Permission Prompt on page load” option, the permission prompt will be shown automatically without awaiting a trigger.
2. Integrating the SDK into Your Website
Once you have created the Application in the D·engage platform, your website integration details will appear as shown below.

Web Application Details
2.1 Download the service worker file.
Download the Service Worker file and add it to your website’s root folder. Only one Service Worker file should be used for generating a Web Push token. If another Service Worker is already generating a token, it must be removed first before adding the D·engage Service Worker file.
2.2 Insert the SDK Injection Script.
Insert the provided code snippet into your website’s HTML code. If you enable the “Show Permission Prompt on page load” option, the web push integration will work automatically. Otherwise, you can manually trigger the notification prompt using the SDK functions.
3. How to Create an Apple Safari Web Push Certificate
These certificates are required to send web push notifications to Safari users on macOS.
Requirements
- An Apple Developer Account
- Access to Certificates, Identifiers & Profiles in the Apple Developer portal
- The Website Push ID you will use for Safari notifications
- A CSR file (Certificate Signing Request)
3.1 Create a Website Push ID

Website Push ID
If you do not already have a Website Push ID, create one using the steps below:
- Sign in to your Apple Developer account.
- Navigate to Certificates, Identifiers & Profiles.
- Go to Identifiers.
- Click the + button to add a new identifier.
- Choose Website Push IDs.
- Enter a description and identifier.
- Click Continue, then Register.
3.2 Generate a Certificate Signing Request

Certificate Signing Request
You will need a CSR file to create the push certificate.
On macOS (Keychain Access)
- Open Keychain Access.
- From the top menu, click Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority.
- Enter your email address.
- Select Saved to disk.
- Click Continue and save the
.certSigningRequestfile.
3.3 Create the Safari Web Push Certificate

Create the Safari Web Push Certificate
- Go to Certificates, Identifiers & Profiles.
- Select Identifiers and locate your Website Push ID.
- Open it and scroll to the Certificates section.
- Click Create Certificate.
- Upload the CSR file.
- After generation, download the Web Push Certificate (.cer) file.
3.4 Export the Certificate as a .p12 File
D.engage website application will typically require a .p12 certificate.
- Double-click the downloaded .cer file to add it to Keychain Access.
- Open Keychain Access and find the certificate under My Certificates.
- Right-click the certificate and choose Export.
- Select Personal Information Exchange (.p12).
- Choose a password to protect the
.p12file. - Save the exported file.
3.5 Provide the Certificate to Your Application
Upload the .p12 certificate and password to your D·engage Website Application to activate Safari push notifications. Push Notification > Safari

Push Notification > Safari
By creating a Website Push ID, generating a CSR, creating a certificate, and exporting it as .p12, you can successfully enable Safari Web Push on macOS.
4. Usage of the Web SDK
Once you insert the Injection Script into your main HTML file, the SDK’s core functionality starts automatically. This includes displaying Web Push Notification permission prompts and tracking notification subscriptions. Therefore, the initialization function is essential.
initialize accepts optional properties, including trackingPermission. See 4.5 Managing User Identification and 4.7 Setting and Getting Tracking Permission.
<script type="text/javascript">
…….
…….
dengage(‘initialize’);
</script>
4.1 Triggering the Notification Prompt Manually
If you have enabled the “Show Permission Prompt on Page Load” option in the D·engage platform, you don’t need to implement this step. Otherwise, to trigger the prompt manually, use the showNativePrompt or showCustomPrompt functions.
The showNativePrompt function immediately displays the browser’s native permission prompt.
The showCustomPrompt function displays the custom prompt type you selected in your application settings. Once the user accepts, the native browser prompt will be shown.
dengage('showCustomPrompt'); // displays the custom prompt
dengage('showNativePrompt'); // displays the browser’s native promptIf you have a button or banner for requesting notification permission, you can call showNativePrompt in its click handler.
4.2 Getting Notification Permission
You can use the getNotificationPermission function to retrieve the user’s current notification permission status. This function returns a string value that can be 'granted', 'denied', 'ignored', or 'default'.
dengage('getNotificationPermission', function(permission) {
if (permission === 'granted') {
console.log('Permission granted');
} else {
console.log('Permission not granted:', permission);
}
});4.3 Getting the Current Web Push Token
You can use the getToken function to retrieve the current Web Push token. This function returns nullif the Web Push permission has not been granted.
dengage('getToken', function(token) {
if (token === null) {
console.log('Token is not available');
} else {
console.log('Current Web Push token:', token);
}
});4.4 Checking the Web Push Browser Support
You can use the isPushNotificationsSupported function to check whether the browser supports Web Push Notifications. This function returns true if Web Push is supported.
dengage('isPushNotificationsSupported', function(isSupported) {
if (isSupported) {
console.log('Web Push Notifications are supported in this browser.');
} else {
console.log('Web Push Notifications are not supported in this browser.');
}
});4.5 Managing User Identification
When a user logs in, you obtain their user information, including a contact_key. You can set this contact_key to associate the user with their browser. There are two functions for setting and retrieving the contact_key.
If the user is logged in, set their user ID. This is important for identifying users. You can safely call this function on every page — it will not send unnecessary events.
dengage('setContactKey', userId);To retrieve the current user information from the SDK, use the following function:
dengage('getContactKey', function(userId) {
console.log('Current user contact key:', userId);
});You can also get the current device ID from the SDK using the getDeviceId function:
dengage('getDeviceId', function(deviceId) {
console.log('Current device ID:', deviceId);
});Dengage WebSDK generates its own device_id for each visitor and each browser. If you want to use your own identifier for device_id. You can pass it on the initialize method.
dengage('initialize', {deviceId: customDeviceId});Also if you have contact_key data at the start, you can pass it on the initialize method. You can still use the setContactKey method.
dengage('initialize', { contactKey: userId });And if you want to pass them together you can use it like this:
dengage('initialize', { deviceId: customDeviceId, contactKey: userId });Dengage WebSDK starts doing its tasks with the initialize method. When you pass user identifiers on the initialize, SDK uses the data you provided on its tasks from the start. Any task that requires these identifications are going to be correct and consistent from the start. If you have these identifiers before calling the initialize method we recommend using this approach.
initialize also accepts trackingPermission. Pass false to start the SDK with tracking permission disabled. If you omit it, the previous behaviour is unchanged. See 4.7 Setting and Getting Tracking Permission.
dengage('initialize', {
trackingPermission: false
});4.6 Setting and Getting Country Information
For accurate tracking, the country information of web devices should be set on your website. You can use the following functions to set and retrieve this information:
Set the user's country:
dengage('setCountry', 'TR'); // Set country to Turkey
dengage('setCountry', 'US'); // Set country to United States
dengage('setCountry', 'PK'); // Set country to PakistanRetrieve the user's country:
dengage('getCountry', function(country) {
console.log('User country:', country);
});4.7 Setting and Getting Tracking Permission
Use tracking permission to control whether the SDK tracks a visitor, for example until the visitor accepts your cookie consent banner. Tracking permission is true by default.
// Disable tracking
dengage('setTrackingPermission', false);
// Enable tracking
dengage('setTrackingPermission', true);
// Read the current value
dengage('getTrackingPermission', function(isPermitted) {
console.log(isPermitted);
});What happens while tracking permission is false
| Area | Behaviour |
|---|---|
| Events (page views, custom events, cart, recommendation events) | Not sent. |
| Push notifications | Not initialised. Permission prompts are not shown, and showNativePrompt and showCustomPrompt return false. |
| Onsite messages | Messages that don't depend on visitor data (generic messages) are still displayed. Personalised messages are not fetched. |
| Onsite display and click events | Not sent. |
| Onsite display limits | Display and click counts are kept in the page's memory only and reset when the page reloads. |
| Data already stored for a returning visitor | Left on the device, but not used or sent. |
Starting with tracking permission disabled
Pass trackingPermission: false to initialize.
dengage('initialize', {
trackingPermission: false
});- First-time visitor: the SDK does not create a visitor. No device ID, session ID or installation ID is created or stored. Only generic onsite messages are loaded.
- Returning visitor: the SDK starts normally with tracking disabled, and your value overrides the stored one.
- Your own
deviceId: if you pass one toinitialize, the SDK uses it and creates the visitor with tracking disabled. - Omitting the property: the previous behaviour is unchanged.
Enabling tracking after consent
// On every page load: pass the visitor's current consent state
var hasConsent = false; // read this from your consent tool
dengage('initialize', {
trackingPermission: hasConsent
});
// When the visitor accepts
dengage('setTrackingPermission', true);
// When the visitor withdraws consent
dengage('setTrackingPermission', false);When setTrackingPermission(true) is called after a start with tracking disabled, the SDK creates the visitor and sends the subscription. It also fetches personalised onsite messages and initialises push. Values you passed to initialize (for example pageView, cartItems, language) are applied at that point. Calls made while tracking was disabled (for example pageView and setCart) are dropped and not replayed.
When a visitor the backend already knows turns tracking off, the SDK informs Dengage once. It does not repeat the notification until tracking is enabled again.
Version: the
trackingPermissionproperty oninitializeis available from Web SDK 2.5.8. Earlier versions ignore it and start with tracking enabled.
Compliance: this option does not make an integration compliant with KVKK or GDPR by itself. Check your consent flow with your data protection officer.
4.8 Setting Cart Data
You can use these functions to store the user's cart data.
Use the setCart function to send the current cart data to the SDK. This function automatically calculates and adds additional properties to each cart item. These calculated fields include: Effective_price, line_total, discounted_line_total, effective_line_total
dengage('setCart', {
items: [
{
product_id: '123',
product_variant_id: '123',
category_path: 'Electronics > Phones',
price: 1000,
discounted_price: 900,
has_discount: true,
has_promotion: false,
quantity: 1,
attributes: {
color: 'black',
memory: '128GB'
}
// The following properties will be calculated automatically:
// "effective_price": 900,
// "line_total": 1000,
// "discounted_line_total": 900,
// "effective_line_total": 900
}
]
});The function can be called using either the setCart name or its ec: prefixed version ec:setCart.
4.9 Setting Log Level
You can use this function to control the SDK’s log output in the browser console. This is useful for debugging or monitoring SDK activity.
Use the setLogLevel function to specify the desired log level.
Available levels are: none – Disable all SDK logs. info – Show informational and status messages. warn – Show warnings and errors. error – Show only error messages.
// Show informational logs
dengage('settingLogLevel', 'info');
// Show only warnings and errors
dengage('settingLogLevel', 'warn');
// Show only error messages
dengage('settingLogLevel', 'error');
// Disable all SDK logs
dengage('settingLogLevel', 'none');Log messages will be displayed in the browser’s developer console based on the selected level.
4.10 Exporting Logs
You can use this function to download the SDK logs as a JSON file.
Use the exportLogs function to download all available SDK logs in JSON format. The file will be saved to the user’s computer through the browser’s download mechanism.
// Export all SDK logs as a JSON file
dengage('exportLogs');4.11 Sending Device (Browser) Custom Events
Please refer to Custom Event Setup.