This guide will show you how to send web pop-ups and push notifications.

If you haven’t already completed the web quickstart guide, please complete that first before following this guide. The quickstart guide will show you how to setup CleverTap’s JavaScript library on your website, track events, create user profiles, and engage users by showing them a notification.

Web Pop-Ups

A CleverTap web pop-up is a modal alert-type message view displayed by CleverTap in your desktop or mobile website.

CleverTap web pop-ups come in two types:

  • Simple Web Pop-up Notifications. You can use these templates to create your notifications including a box notification, a banner notification, and interstitial notification.
  • Exit Intent Notifications. These are displayed just before the user exits your site. These are available for desktop only.

User clicks on a web notification can be silent, open a url or invoke a javascript function. Custom key value pairs can also be passed to the invoked javascript function. You may also include a pre-set or custom image to be displayed in the notification.

Click Tracking

Currently, we don’t support tracking clicks on custom web pop-ups.

Adding Close buttons to web pop-ups

You can add a close button to your web pop-up.

Box

<div class="btn">CLOSE</div>
<script>
var btn = document.querySelector('.btn');
var wrapper = window.parent.document.getElementById('wizParDiv0');
btn.addEventListener('click', closePopUp);
function closePopUp()
{ wrapper.remove(); }
</script>

Banner

<div class="btn">CLOSE</div>
<script>
var btn = document.querySelector('.btn');
var wrapper = window.parent.document.getElementById('wizParDiv2');
btn.addEventListener('click', closePopUp);
function closePopUp() { wrapper.remove(); }
</script>

Interstitial

<div class="btn">CLOSE</div>
<script>
var btn = document.querySelector('.btn');
var overlay = window.parent.document.getElementById('intentOpacityDiv');
var wrapper = window.parent.document.getElementById('intentPreview');
btn.addEventListener('click', closePopUp);
function closePopUp()
{ overlay.remove(); wrapper.remove(); }
</script> 

Defining a Custom Rendering Listener

Using this custom callback, you will be able to control the look, feel and location of the web pop-up which you create in your CleverTap Dashboard.

You need to explicitly call clevertap.raiseNotificationViewed(); & clevertap.raiseNotificationClicked(); to ensure that notification views and clicks are tracked in your CleverTap Dashboard.

To define the callback and raise the clicked and viewed events, you need to add the following snippet to the embed code.

clevertap.notificationCallback = function(msg){
      //raise the notification viewed and clicked events in the callback
      clevertap.raiseNotificationViewed();
      console.log(JSON.stringify(msg));//your custom rendering implementation here
      var $button = jQuery("<button></button>");//element on whose click you want to raise the notification clicked event
      $button.click(function(){
         clevertap.raiseNotificationClicked();
      });
};

The msg will be in the format below. msgId contains the campaign id and the date stamp so you can programmatically decide whether to show the notification or not. kv contains the custom key value pairs.

{
    "msgContent": {
        "title": "hello title!",
        "description": “hello message!"
    },
    "msgId": "1439796272_20160219",
    "kv": {
        "key1":"value1",
        "key2":"value2"
    }
}

Web Push

Web push notifications are currently supported for Chrome version 50 for Desktop and Android and work only on HTTPS sites (and on localhost).

Add the CleverTap JavaScript Library

Integrate the CleverTap JavaScript library by following the Web Quickstart Guide.

Integrate FCM and CleverTap

FCM has deprecated its existing web push protocol post-July, 2019 and moved to the VAPID protocol.

If your server key and sender ID were generated before July 2019, the legacy protocol will continue to work. However, if they were generated after July 2019, only VAPID protocol will be supported.

We recommend that you use VAPID protocol due to increased security.

Legacy protocol steps:

Get your Sender ID and Server Key. In the CleverTap Dashboard, go to Settings → Integrate Web Push and add your Server Key.

VAPID protocol steps:

Get your Public and Private key pair from Firebase. In the Firebase console, go to your Project > Project Settings > Cloud Messaging > Web Configuration > Generate Key Pair

In the CleverTap Dashboard, go to Settings > Integrate Web Push > Select use VAPID Spec and add the generated Public and Private Key Pair.

Re-subscription of users

After you move from legacy to the VAPID protocol, we recommend that you re-subscribe the users with legacy tokens to move them to VAPID. In this case, the permission pop-up will not re-appear. The subscription will happen in the browser's background silently.

However, to help you in the migration process, we will also support the legacy protocol simultaneously even though VAPID is enabled. This will ensure web push delivery across all your subscribed users.

Add the Service Worker File

Push notifications on Chrome make use of a special script called a service worker that listens for web pushes. Since the execution of these scripts is managed by the browser in the background, users can receive push notifications from your website even when they’re not on your site. To get started, download the service worker file we have provided and copy it in your document root of your website, such that it’s publicly accessible.

Download the service worker file from here. As mentioned above, you’ll have to host this file in your document root.

Integration with Existing Service Worker File

Import CleverTap's service worker at the start of your existing service worker. Add the following code snippet :

importScripts('https://s3-eu-west-1.amazonaws.com/static.wizrocket.com/js/sw_webpush.js');// remove CleverTap server worker from your root folder

Specify the Sender ID in manifest.json File

Note

This step is required only if you are using the legacy protocol.

In order to register the service worker and subscribe for push notifications, you need to specify your Sender ID inside a website manifest file.

If your website already has a manifest, simply add the following property to it. Your Sender ID is your FCM Project Number (12 digit number) and not your API Key.

{
  "gcm_sender_id": "YOUR_SENDER_ID"
}

If you don’t have a manifest file yet, create a new file called manifest.json and add it in the document root of your website. Ensure that you specify the "name" and "gcm_sender_id" parameters, where "name" is the name of your brand (e.g. “Acme Fashion”).

Here is a sample manifest.json file.

{
  "name": "Acme Fashion | Latest in fashion world",
  "gcm_sender_id": "1234567890" // replace with actual value
}

Then, in all your HTML files, include the below snippet in the header.

<head>
  <link rel="manifest" href="/manifest.json">
</head>

Requesting User Permissions

Now that you have a service worker and manifest set up, it’s time to start asking users if they want to subscribe to Web pushes. For flexibility, CleverTap provides you with the ability to ask for notifications based on context and user actions.

As a general rule, we highly recommend asking for permission from users only after they’ve spent some time on your website, and completed an action of significance. Do not ask new users to subscribe for notifications as soon as they land on your site.

For example, after a user has completed a transaction, you may call the function below.

clevertap.notifications.push({
    "titleText":'Would you like to receive Push Notifications?',
    "bodyText":'We promise to only send you relevant content and give you updates on your transactions',
    "okButtonText":'Sign me up!',
    "rejectButtonText":'No thanks',
    "okButtonColor":'#f28046'});

The general format for creating the popup is below.

clevertap.notifications.push({
    "titleText":popupTitleText,
    "bodyText":popupBodyText,
    "okButtonText":okButtonText,
    "rejectButtonText":rejectButtonText,
    "okButtonColor":okButtonColorInHex});

Custom service worker format for notification permission popup

clevertap.notifications.push({
       “titleText”:‘Would you like to receive Push Notifications?,
       “bodyText”:‘We promise to only send you relevant content and give you updates on your transactions’,
       “okButtonText”:‘Sign me up!,
       “rejectButtonText”:‘No thanks’,
       “okButtonColor”:#f28046’,
       “askAgainTimeInSeconds”:5,
       "serviceWorkerPath": "/foo/my_sw.js" // path to your custom service worker file
   });

If a user blocks the native chrome permissions popup, the user is lost forever (unless the user clears their browser settings). However, if you are using the Clever popup, you get the advantage of asking the same user again for permission after a defined period.

Permission Frequency
To ensure that users are not asked for permission too frequently, our API ensures that calling clevertap.notifications.push does nothing if the user has rejected the dialog less than one week ago. Once a week has passed by, calling the function will display the dialog as expected. This eliminates the need for you to implement a separate check before calling the function.

To set a separate frequency, send "askAgainTimeInSeconds":time_in_seconds along with the above object.

To skip the Clever popup, send "skipDialog":true along with the above object.

Migrating from Other Services

If you are migrating from a different web push notifications provider, you may be concerned about asking subscribed users to enable notifications a second time.

Note that, if a user has already enabled notifications on your host domain, calling clevertap.notifications.push will not display the popup for that particular user, and the registration will automatically be migrated to our new implementation.

You can use the below custom service file which should only be used during the migration phase. Once the token migration of most of your users is complete, you can replace it with the parent service worker.

importScripts('https://s3-eu-west-1.amazonaws.com/static.wizrocket.com/js/sw_webpush_only_registration.js');

End User Session

When a user logs out of your site, you can end the CleverTap session by calling the clevertap.logout(); method.

Debugging

Error messages and warnings are logged to the JS console of the browser.

Verbose logging: enable verbose logging of all communication with the CleverTap servers by setting the WZRK_D variable in sessionStorage. In the developer console of your browser type: sessionStorage['WZRK_D'] = '';

Updated 17 days ago

Web


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.