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

Skip to end of metadata
Go to start of metadata

Getting Started

Version

A new major version has been released. If you want to create a new application, please check this version instead.

The Accengage Web SDK provides a javascript module that will enable your web application to use with ease Accengage's notification management.

The last version was 2.1.x and worked with Chrome 44+, Firefox 46+

Integration

The integration is done in three simple steps.

Create your application

Our support team will create your Web Application. To do so, will ask you to provide some basic information:

FieldDescription
Registered DomainsDomain names with which you want to use our Web SDK. For example if you have different top-level-domains ".com" and ".fr", you must register them as two distinct domains. The same logic applies if you have an optional "www." subdirectory.
Google API Key

In order to push notifications to your Chrome users, it will require an Google API Key" and a Android Sender Id.

If you do not already have a FCM or GCM project, you have to first create a project on Firebase.

Then go to "Settings > Cloud Messaging", and retrieve your Server Key as for the Google API Key, and your Sender ID as for the Android Sender ID.

Android Sender ID
Default URL on Notification ClickA default URL (generally your website's home page) used to open a new window when the user clicks on your notifications. Obviously, you will be able to use a more specific URL while creating a message.
Default Notification ImageA default image displayed on your notifications. Same as above, you can use a specific image when editing messages.

 

Paste a code snippet into your website pages

The integration of the SDK in your website is the easy part. Once you've registered your Web app on the Accengage interface, we will send you the information you need for the SDK's integration such as your partner id, a private key and a master domain name. You just need to paste a small piece of JavaScript into your pages, replacing the {{ Master Domain }} with the one we provided after the registration of your Web app on our interface :

 

Code snippet to paste

Paste the snippet into your pages so that it appears before the closing </head> tag

Use another reference name for the main SDK object

In the above snippet code, you will see in the last line a few defined variables. You can edit the "ACC"  <string> for another one. For example, if you set the value to "foo", you would use the SDK API with the foo.push( ) method.

Customize the SDK

When these steps are done, the SDK is fully operational. To edit specific SDK options, such as the integration or configuration of plugins, you can go to our interface > Settings > Manage Applications > Edit your application > Plugins configuration. All the changes will be live on your website. See the Configure your application section below for more informations.

 

Configuring Your Application

How to add a Plugin to the SDK ?

On our interface > Settings > Manage Applications > Edit your application. You will have a Plugins configuration parameter. It contains all the plugins and configuration you want to inject in your websites. The parameter is JSON formatted. Just remember that the Core plugin and Push plugin are automatically injected.

 

Core plugin

The Core plugin is automatically added to the SDK. Basically speaking, this plugin enables the SDK to create or edit information on the user that is currently navigating your website. This plugin doesn't need any particular configuration in the Plugins configuration parameter.

 

Push plugin

The Push plugin is automatically added to the SDK. It enable the SDK to return two types of information : how to transform the current user as an optin one, and when to do it. Technically speaking, this optout-to-optin process will follow these steps :

  1. the non-yet-optin user is currently navigating your website. A HTML Anchor (</a> tag) invites him to subscribe to web push notifications.
  2. the link opens a new HTML Window (a new browser tab for mobile users ; or a popup window for desktop users) asking for a native notification permission. This page (optout-to-optin landing page) is hosted on the alias domain set up when your application was created on our interface.
  • The process will always follow these steps : a link in your page > the opening of a landing page through a new window.
  • Please note, the Push plugin can be fully configured according to the way you want to implement the link towards the native permission or the content you want to display to the user in the landing page
  • For example, you can either configure the plugin to let the SDK do the optout-to-optin process by its own ; or legitimately configure it to create the most adapted process according to your website

Push plugin configuration

The configuration of the Push plugin is set inside the JSON Plugins configuration :

ParameterTypeDefaultDescription
scenario<string>"none"

a scenario initiated as soon as the SDK is loaded. Available scenarios :

  • "none"
  • "showAlert" : shows the HTML alert (cf below API Documentation push:showAlert section)
alertOptions<object>see belowthe object containing the parameters of the HTML alert
landingOptinOptions<object>see belowthe object containing the parameters of the optout-to-optin landing page
customError<object>see belowthe object containing the parameters of the Chrome Error Notification
For example

 

HTML Alert option

The HTML alert is an interactive block injected by the SDK inside your page in order to identify users that are willing to receiving push notifications but not yet optin. It is an optional feature that can help you to do the first step of the optout-to-optin process : display a link intended to open the optout-to-optin landing page.

To use this feature, just set the Push configuration scenario to "showAlert" (see above), or use the push:showAlert command (described here).

The configuration of the HTML alert is set inside the Plugins configuration push.alertOptions. You can access this page to see an example customization :

ParameterTypeDefaultDescription
theme<string>"light"

the selected theme to customise the HTML alert. Available themes :

  • "light"
  • "dark"
  • "blank" : no CSS injected, you have to customise the alert by your own

With the "blank" theme, don't forget to create your own CSS rule for the modifier class .acc-alert--hidden (with a "display: none" for example)

position<string>"topRight"

the position of the HTML alert. Available value :

  • "topRight"
  • "bottomRight"
  • "bottomLeft"
  • "topLeft"
reAskingDelay<number>1

a parameter defining the number of hours to wait before showing the HTML alert again. Please note that the SDK uses a COOKIE to check this step. Also, if the user clicks on the accept or deny link, the HTML alert will not be shown again.

When set to 0, no delay will be taken into account

contents<object>see belowa list of selected contents displayed to the user

Here is the list of contents used in the HTML alert (you can include some <html> code) set in the push.alertOptions.contents object :

Content fieldDescriptionDefault value
miscthe <string> value hydrating all the ".acc--miscContent" DOM Elements contained in the HTML alertnone
deny   ″   ″   ″ hydrating all the ".acc--denyContent"    ″   ″   ″none
accept   ″   ″   ″ hydrating all the ".acc--acceptContent"    ″   ″   ″none

For more details concerning the contents object, read this section

Optout-to-optin landing page option

As described above, the optout-to-optin landing page is a new window needed to finalise the second step of the optout-to-optin process. Hence, accessing this page is mandatory to turn the user into an optin one. You can see in the screenshot below that a native notification permission is displayed inside the page.

 

The configuration of the optout-to-optin landing page is set inside the Plugins configuration push.landingOptinOptions

ParameterTypeDefaultDescription
theme<string>"light"

the selected theme to customise the optout-to-optin landing page. Available themes :

  • "light"
  • "dark"
  • "black"
width<number>462a pixel value defining the width of the popup window
height<number>135a pixel value defining the height of the popup window
withAppIcon<boolean>falsea flag defining if you want to display your Application Icon (cf above section Getting started > Create your application)
contents<object>see belowa list of selected contents displayed to the user

Here is the list of contents used in the optout-to-optin landing page set in the push.landingOptinOptions.contents object :

Content fieldDescriptionDefault value
askcustom <string> value (for exemple to explain why the user needs a push notification permission)none
granted   ″   ″   ″  when the user has granted the notification permissionnone
denied   ″   ″   ″  when the user has denied the notification permissionnone
error   ″   ″   ″  when an error occurred during the optout-to-optin process
  • "en" : "An error occured, please try again later"
  • "fr" : "Une erreur est apparue, veuillez recommencer plus tard"
close   ″   ″   ″  the page does not close itself
  • "en" : "You can now close the page"
  • "fr" : "Vous pouvez désormais fermer la fenêtre"

For more details concerning the contents object, read this section

Custom Error option

ParameterTypeDefaultDescription
contents<object>see belowa list of selected contents displayed to the user
Content fieldDescriptionDefault value
titlenotification's title"Oups"
messagenotification's message"An error occurred while displaying a notification"

For more details concerning the contents object, read this section

Facebook Messenger plugin Configuration

(question) Available version: 2.2+

The configuration of the Facebook Messenger plugin is set inside the JSON Plugins configuration :

ParameterTypeDescription
fbAppId<string>mandatory, the ID of your Facebook Application
fbPageId<string>mandatory, the ID of your Facebook Page
For example

 

How the "contents" object is set ?

The contents <object> is used to display a specific content to the user. It contains a list of properties, according to the plugin configuration itself. Hence, here is a possible example of configuration :

Using the Debug Mode

Accengage WEB SDK provides a Debug Mode allowing you to keep a stack trace accessible through your browser console.

The debug mode can also bypass the application's settings cache. For example, you have made some changes on our interface for your application, and you don't want to wait thirty minutes to see the modifications. Use the debug mode avoid this wait and see the changes (it won't destroy the current cache though, other users will keep seeing the cached version).

To use the debug mode, just follow these steps :

  1. Enable the checkbox on our interface > Settings > Manage Applications > My application > Allowing debugging.
  2. It will create an "ACCdebugKey". To activate the debug mode, you just have to include it in your page URL as query string parameter
  3. For example, if your current page is http://myWebsite.com/page.html, just add : http://myWebsite.com/page.html?ACCdebugKey=XXXX

On Google Chrome (or Firefox), you can access the console by

  • Using the keyboard shortcuts
    • On Windows and Linux: F12
    • On Mac: Cmd + Option + I
  • Then go to the ‘Console’ panel

 

 

API Documentation

How to use the SDK inside your pages ?

In general, when you want to communicate with the SDK API, you will need to create a command by calling the main SDK 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 example:

Then, you just need to use the push method of the ACC object to create a new command. For example:

The three parameters mostly accept :

ArgumentTypeDescription
1 → name<string>always required, containing the plugin name and method name to call, separating by a ":"
2 → options<*>containing the options of the command
3 →icallbacks<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 SDK is not fully loaded when the command is created, it will be put inside a queue, waiting for the SDK to load. When the SDK is loaded, the stored commands, or next created commands, will be properly consumed.

 

Core plugin

core:updateDeviceInfo

Use this command whenever you want to update the current user's information. Some fields, that we use internally, are filtered.

ArgumentRequiredTypeDescription
optionsyes<object>a list of fields <string> with value <string|number>
callbacksoptional<object>
  • "onSuccess" : <void> 
  • "onError" : <string> label error
For example

core:isOptin

Use this command when you want to know if the current user is optin

ArgumentRequiredTypeDescription
optionsnot used  
callbacksyes<object>
  • "onSuccess" : <string> first optin date
  • "onError" : <string> label expliciting the reason why the user is not optin
For example

core:getDeviceID

Use this command to retrieve the current user device ID

ArgumentRequiredTypeDescription

options

not used  
callbacksyes<object>
  • "onSuccess" : <string> device ID
  • "onError" : <string> label error while retrieving the user device ID


For example


The device ID value can change through time, e.g. when the user clears data from the browser cache.

core:addCustomListeners

Use this command to register your custom listeners to an event triggered by the SDK

ArgumentRequiredTypeDescription
optionsyes<object>

a list of event names <string> with listener <function>. Available Core plugin events :

  • "sdkLoaded" : <void> this event is retroactive, i.e. if you use this command after the SDK has been loaded, your provided listener will be triggered. It is also a one time event
callbacksoptional<object>
  • "onSuccess" : <array> returning the events that have been listened
  • "onError" : <string> label expliciting the reason why no events have been listened
For example

 

Push plugin

push:isCompliant

Use this command when you want to know if the current user is compliant to web push notification. This method could be useful, especially if you want to know if the user has denied the native notification permission.

ArgumentRequiredTypeDescription
optionsnot used  
callbacksyes<object>
  • "onSuccess" : <void> compliant to push
  • "onError" : <string> label expliciting the reason why the user is not compliant
For example

push:showAlert

Use this command when you want to show the HTML alert to the user.

ArgumentRequiredTypeDescription
optionsnot used  
callbacksoptional<object>
  • "onSuccess" : <void>
  • "onError" : <string> label error
For example

push:launchLandingOnClick

Use this command to bind one or more DOM Anchor Elements (</a> tag) to launch the optout-to-optin landing page on click.

ArgumentRequiredTypeDescription
optionsyes<array>of <string> containing selected anchors to bind. The value must start with "#" or "." (ID or ClassName)
callbacksoptional<object>
  • "onSuccess" : <array> provided elements that have been utterly binded
  • "onError" <string> label error
For example

push:addCustomListeners

Use this command to register your custom listeners to an event triggered by the SDK

ArgumentRequiredTypeDescription
optionsyes<object>

a list of event names <string> with listener <function>. Available Push plugin events :

  • "landingFeedback:optin" : <void> triggered when the optout-to-optin landing page returns that the user has granted permission and is now optin
  • "landingFeedback:softOptout" : <void> same thing, but triggered when the user has not granted the notification permission. In this case, the user can still be optin.
  • "landingFeedback:hardOptout" : <void> same this, but triggered when the user has denied the permission, hence he's definitely optout
callbacksoptional<object>
  • "onSuccess" : <array> returning the events that have been listened
  • "onError" : <string> label expliciting the reason why no events have been listened
For example

 

Facebook Messenger plugin

(question) Available version: 2.2+

fbMessenger:generateButton

Use this command to generate a Facebook Messenger button. You can create buttons as many as you want.

ArgumentRequiredTypeDescription
containerIdyes<string>the ID of your DOM Element that will contain the generated button
coloroptional<string>

a constant defining the color of the generated button. Available colors :

  • "blue" default if not provided
  • "white"
sizeoptional<string>

a constant defining the size of the generated button. Available sizes :

  • "standard"
  • "large" default if not provided
  • "xlarge"
callbacksoptional<object>
  • "onSuccess": <void>
  • "onError": <string> label expliciting the reason why no button has been generated
For example

Use Cases

A deeper look at the optout-to-optin customization

When you start implementing our Web Push technology on your website, a major thing to think through is your optout-to-optin scenario, and how you want to customize it. Some people want to have full control of this part. That's why we created a very modulable system to adapt to your own thinking, but we also propose a turnkey solution for quick integrations. Click here to learn more about it.

Tag Management Systems

If you want to integrate our SDK with a Tag Management System, we have some examples here.

FAQ

If you have issues concerning the use of the SDK, our FAQ is available here.

  • No labels