Our documentation is changing, please click here to enjoy it!

Skip to end of metadata
Go to start of metadata

2.1 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

2.2 Mandatory web SDK integration steps

2.2.1 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

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


2.2.2 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”.

2.3 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.

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:

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

For instance:

The three parameters mostly accepted are:

ArgumentTypeDescription
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

To summarize, the ACC JavaScript Object is set thanks to the snippet code you have previously added in your page. If the library is not fully loaded when the command is created, it will be put inside a queue, waiting for the library to load. When the library is loaded, the stored commands, or next created commands, will be properly consumed.

2.4 Updating the SDK version (migration guide)


    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.

     

    Important

    This new opt-in process requires to work a domain under HTTPs protocol.

    Note that if you migrate to 3.3.x and have a domain working under HTTP protocol, the current opt-in process will continue to work like others versions below 3.3.x of the SDK Web


    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"

     

    Important

    At this stage, please keep the checkBox 'Use my own domain name' unchecked


    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 "acc_sw.js" and "acc_ww.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 :

     


    Important

    Those 3 files are only available for download to applications configured in the Accengage Dashboard with SDK's version number above 3.2.x (step 1/3)

    Those files should be uploaded to the root directory of your website, unless you already host a "manifest.json" file, you should merge the lines generated by the "manifest.json" downloaded from our interface to the "manifest.json" hosted on your server.

    Important

    You need to reference "manifest.json" in all your pages by including this tag in the <head> :

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


    If the "manifest.json" doesn't reside in your root directory please reference it like below :

    <link rel="manifest" href="/path/to/your/manifest.json">


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

    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"

     

    Note

    Please keep the field "master domain name" unchanged.

    It should still be the domain provided by Accengage during your first integration.

    The master domain is referenced as .by-accengage.net or .notification.group if you have subscribed to a custom domain.

     

     

    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 3. 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

    Migrating from Cookie to LocalStorage

    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 :

    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 :

    Version 2 documentation

    Follow this link to check our previous documentation for the version 2

    • No labels