Web SDK Integration

Overview

The Accengage Web SDK consists of a Javascript module, which simplifies and manages the interaction with the Accengage Push Notification software.

By adding the Accengage's snippet inside your html code, you will be able to handle :

  • The Web Push Notification Opt-in process, in order to collect user permission (this is detailed in the next section)
  • The Web Push Notification reception, display and tracking
  • User profile and behaviour tagging in order to collect the data you wish and store it on the Accengage servers for targeting purposes (detailed in the section "User Profile and Behaviour tracking").

The successive steps in order to integrate and use the Accengage Web Push software are:

  1. Copy and paste Accengage Snippet (see below) into your website, that will call and integrate the Accengage SDK
  2. Customize the opt-in process, to maximize opt-in user collection and adapt it to your design and user experience
  3. Tag relevant information on users, using Javascript methods, which will interact with the Accengage SDK.

When you play the video, click on HD to enhance video quality

Mandatory web SDK integration steps

Paste a code snippet into your website pages

Accengage has developed its Web Push Notification SDK so as to simplify at maximum the integration process for you. As a result, you just need to copy and paste a Snippet into your website pages, that will call and integrate the Accengage SDK, and most of the work will be done! No need to host files, maintain them etc.

The integration of our library in your website is simple.

Once your Web app is registered on the Accengage Interface, you'll receive your partnerID and Master Domain name (see Section 1) .

You just need to  paste a small piece of JavaScript  into your pages, replacing the  MASTER DOMAIN   referenced below with the one which was provided to you:

Code snippet to paste

(function(l,o,a,d,i,n,g,w,e,b){
  g='AccengageWebSDKObject';w='script';l[g]=l[g]||{};l[g][n]=d;
  l[d]=l[d]||[];l[d].p={'date':1*new Date(),'window':l,'document':o,'params':a};
  e=o.createElement(w);b=o.getElementsByTagName(w)[0];e.async=1;
  e.src='https://'+n+i+'/init.js';b.parentNode.insertBefore(e,b);
})(window,document,{},'ACC','/pushweb/assets','MASTER DOMAIN');
// Replace the reference `MASTER DOMAIN` with the domain provided by Accengage

Use another reference name

In the above snippet code, If you would like to use another reference name instead of ‘ACC’, in the  snippet code, you will notice in the last line a few defined variables.

You can edit the  "ACC"   <string>  parameter for another one. For  instance , if you set the value to  "foo" , you would use our library with the  foo.push( )  method.

From there, the Web Push Notifications are functional, and you can test sending Web Push Notifications!

We do recommend however to go further and customize the opt-in process (read the next section), and to set some tags for relevant targeting.

In order to customize the experience further or to activate some functions for tracking purposes, you will need to create some commands within the Javascript. To see how to proceed, please read the beginning of Section 4, or the beginning of Section 7

Test sending Web Push Notifications

In order to test a Web Push on your own browser and device, you can send a simple Web Push Notification targeted on yourself.

For that purpose, you need to find your own Device ID and create a test segment within the Accengage dashboard.

Go to the Accengage Dashboard, and open it with the browser you wish to target.

Go to Targeting > Search  or to  Targeting > Segments/Lists > Add New Segment > Manage Criterion.

Click on the link “Want to find your Device Id? Click here”. Your Device ID will appear:

Now that you have retrieved your Device ID, you can create a test segment to target your device, and send a simple Web Push Notification on this test segment.

If you would like more help on how to create a test segment and how to send a simple Web Push Notification, you can follow these User Guide links:

Segments and static lists

Editing sending and scheduling a web push

That’s it, you should be able to send your first Web Push Notification!

Of course, we recommend you to go further and to:

  • Customize the opt-in process  see the next section  
  • Collect user data to enrich the user profiles for more targeted and relevant messages ➔ see the section “User Profile and Behaviour tracking”.

Useful commands

This first step is to edit the "MASTER DOMAIN" <string> with the master domain created with your Accengage Application. Check this section of our guide to have more information about process of creating an Accengage Web Application.

// If the snippet is still onload, it will create an array
// Otherwise, it will use the ACC object previously declare in the code snippet
var ACC = ACC || [];

/*************************************/

// In the most common scenario, the library will be accessible through your global `window` scope
// If you develop with IIFE, don't forget to export it
(function(global) {
    global.ACC = global.ACC || [];
})(window);

In order to use the more advanced functions that will be described in the following sections (for opt-in process customization, or tagging purposes), you will need to create some commands within the Javascript.

In general, when you want to communicate with the SDK, you will need to create a command by calling the main JavaScript Object ‘ACC’ (read this section if you want another reference name). As the code snippet could still be on a loading state (because you are using a tag manager for example), we suggest you declare the ‘ACC’ object as an <array> as soon as possible.

For instance:

var ACC = ACC || [];

Then you just need to use the ‘push’ method of the ‘ACC’ object to create a new command.

For instance:

ACC.push([ "plugin_name:method_name" , options, callbacks ]);

The three parameters mostly accepted are:

Argument Type Description
1 → name <string> always required, containing the plugin name and method name to call, separating by a ":"
2 → options <*> containing the option of the command
3 → callbacks <object> containing callbacks <function> type, applied when the command has been consumed

Updating the SDK version (migration guide)

Fromm 3.x.x to 3.3.x

If you want to migrate to version 3.3.x of our SDK Web and benefit of the new and easier optinization process for your users engagement, please follow these next steps.

We advise to **follow these steps after each others** for the proper conduct of the migration and let the SDK Web operate effectively.

Mandatory steps :

(1/3) Edit the version number of your application :

To get access to the new opt-in process of the SDK Web you should set your application version to 3.3.x.

To do so, please go into your Accengage Dashboard : Settings > Manage application > Edit > Field Version : change it to our last version available "v3.3.x"

Click on "Save".

Changes will take approximately half an hour before getting live.

(2/3) Download and host to your web server the mandatory files :

Once you've upgraded the version number of your application, to operate the new opt-in process needs a zip file to be downloaded from our interface.

To download the zip file, please go to our interface > Settings > Manage Application > Click on the download icon at the right :

Once you've downloaded the ZIP file, you should extract files from this ZIP. You should obtain 3 files :

  • acc_sw.js
  • acc_ww.js
  • manifest.json

Once extracted, before going to the next step, please upload those files to the root directory of your website.

The files "accsw.js"_ and "accww.js"_ will be called by the SDK and the file "manifest.json" just has to be referenced in the pages where the snippet will be present.

The optinization on your own domain needs a service worker running on your domain to operate (acc_sw.js)

If you already host a service worker on your website, you'll have to merge the Accengage one with yours.

To do so, add the lines below at the end of your service worker script :

 

var swURI = 'https://' + this.location.hostname + '/acc_sw.js';
importScripts(swURI);

(3/3) Enable optin with your own domain name :

Finally to set up the opt-in process you should enable it through the Accengage dashboard and the "modify web application" modal screen, to do so please go to our interface > Settings > Manage Application > Edit your Web App > check "Use my own domain name"

Mandatory steps

(1/2) Change your snippet

First of all, you have to change your old snippet for this new one . This snippet will work with every version. So even if you have a version 2 or 3, this snippet will launch our library in both cases.
Please keep in mind that if you don't upgrade your snippet, the version 3 would not be able to work.

(2/2) Edit the configuration of your application

Only then, you will be able to set your application from a version 2 to

  1. To do so, please go to our interface > Edit your application > Version : and change it for our last version available "v3.1.x" Changes will take approximately half an hour before getting live.

Heads up! We have made few changes you need to know

Regarding our built-in HTML Alert, we previously used Cookies to store the state of the component. For this new version, this state is now store within a LocalStorage. You could see some minor issues while migrating from version 2 to 3, e.g. a display of the alert although the user had previously denied it. It won't affect optin users, nor hard-optout users (that have previously denied the permission).

If you have followed one of our previous article about the use of Google Tag Manager

Please note that an edition could be necessary to make some "Tags" still working with the new library version.
It concerned the article published from last year to February 2017, and concerned about one tag made in the "Create basic interaction" and another one with the "Create complex interaction" sections.

What you have to change for the "Create basic interaction"

The documentation advised you to set your tag like this :

We advise you a simpler approach, since our snippet have changed a little bit for the newly version 3 :

(function(global){

  // Retrieve the main object
  // (if the SDK is not fully loaded, the commands will be pushed
  // into an array queue)
  global.ACC = global.ACC || [];

  // In this example, we create a "core:isOptin" command
  // (check our documentation to see other possible commands)
  global.ACC.push([
    'core:isOptin',
    null,
    {
      "onSuccess": function(firstOptinDate) {
          console.log( "this user is optin since : " + firstOptinDate );
      },
      "onError": function(err) {
          console.log( "this user is optout", err );
      }
    }
  ]);
})(window);

What you have to change for the "Create complex interaction"

Regarding the Custom HTML Tag "Accengage SDK API", the article guided you to set it like this :

We guide you now with a simpler approach :

(function(global,data){

    // Retrieve the main object
    // (if the SDK is not fully loaded, the commands will be pushed
    // into an array queue)<link rel="manifest" href="/manifest.json">
    global.ACC = global.ACC || [];

    // Retrieve the command, GTM keeps a reference to inner command Object,
    // so we clone the command ...
    var command = JSON.parse(JSON.stringify(data));
    // ... and delete the original
    data[1] = null;
    delete data[1];

    // Push the command
    global.ACC.push(command);

})(window,{{Accengage SDK Push Command}});

Version 2 documentation