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

Skip to end of metadata
Go to start of metadata

[Back] Push Web Summary

Integration

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 library. 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 our library 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 integration such as your partner id 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

Use another reference name

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 our library with the foo.push( ) method.

Customize the library

Collecting user's personal data

Introducing in version 3.2.x this new version of the Web SDK has introduce a new way of collecting user's personal data. Respectful of the new epoch of personal data privacy. This new version enforce the user's agreement regarding the way we collect the personal data. Integrating this new version of the SDK is straightforward and is based on the users willingness. Indeed we have now exposed 2 new commands which will help you to get and set the user’s agreement and thus start the optin process and collect personal data. Please refer to the collect plugin documentation.

How to get the user privacy

Integrating this new privacy system required for you to create a way for getting the agreement of the user. As an example you can create a banner or even better reuse an existing web creation in order to get the user agreement. Below is an example of a banner

 

Whenever the user will agree or not you should call the collect:setOptinData method. This method will save the user agreement and based on this value will do the rest of the actions regarding the way we can collect the user’s personal data. Below is a description of different kind of value you can pass

User agreementoptinDataSDK Actions
Yestrue
  • wake up the SDK

  • collect the datas

  • create / retrieve a profile

  • start the optin process

Nofalse
  • wake up the SDK

  • remove the existing profile (if it exist)

  • Disable the SDK

  • Disable the push

Note

Note that you can pass from a no → yes state. Passing from no to a yes state will create a new user

Different uses cases of collecting personal datas

The new privacy feature in the new version take account of the previous version of the SDK. Indeed users who are optin with a previous version of the SDK will be automatically update. This mean that each profile will be preserve with the user’s agreement. Please refer to the table above for more detail. Since this feature change the way we collect datas below is the scenario regarding how we collect the data

CaseDescription
User who’s optin with previous version of the SDK

If the user agree at Accengage collecting personal datas we will the same user's profile will be continued to be used. The rest of the SDK will work as intended.

User who has been previously optin but refused to collect personal data

If the user said no we’ll then remove the whole user's profile. This also imply to remove the service worker (component which help accengage to send push notification to the user).

New user said no

The SDK will stay in a froozen state. Therefore no data will be collect nor upload to Accengage's database.

New user said yes The SDK will wake up and begin to collect the user personal data and prepare the optin process.

 

Activating the new collect feature

Enabling the collect feature required that your app should be updated to version 3.2.x. Upgrading to this new version enable you to activate the collect feature

 

When enabling this feature the SDK will then wait for the user agreement. We want to reinforce that it’s highly important to implement the collect user agreement.
         

Using your own method to collect the user’s agreement

If you have already collected the user’s agreement by using an other method than the ones provided by Accengage. You’re not required to enable the collect checkbox on the Accengage’s interface. You're not required to enable the collect checkbox on the Accengage's interface. Indeed, if the checkbox is checked our SDK will be froozen and no user's data will be collected. So in this usecase we recommend you don't check it.

Customizing the SDK configuration

When these steps are done, the library is fully operational. To edit specific library options, such as the integration or configuration of plugins, you can go to our interface > Settings > Manage Applications > Edit your application > Plugins configuration . We will have to wait for approximately half an hour to see the changes live in your pages (check the debug mode section to learn how you can immediately see the changes). Next sections of this documentation will tell you what are the available options you can configure.

Web notifications

Overview

Our solution will allow you to send web notifications to your users. This section will help you to answer how to transform a current user as an optin one. More specifically, you will learn:

  • the different ways and manners available with our solution, and how it will simplify for you every technical aspects
  • the possibility of customization, i.e. you could let our solution create a simple and generic process, or you could customize this process and treat each user specifically

If you want to know how to use our JavaScript library for specific scenarios, please check our technical API reference.

Optout-to-optin process

Accengage provides you with 2 opt-in process : 

    This optout-to-optin process will follow these requirements : a link in your page > the opening of a landing page through a new window.
    To do so, our library offers a turn-key solution by creating a simple and convenient process in your web pages. Our solution will transform your current user through three simple steps:

     

    Note

    This opt-in process is available for website working under HTTP and HTTPs protocol.

    Starting from version 3.3.x of the SDK Push Web, Accengage allows you to ask for the opt-in through your own domain name.

    This optout-to-optin process will follow these requirements : a link in your page > display of the browser's native permission

     

    Important

    This optout-to-optin process is available only for website working on HTTPs protocol.

     

    In order to benefit this process we recommend you to follow these steps after each other :

    (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 'enable one step-optin' 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.

    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.

    Keep in mind that if you didn't host before your own "manifest.json" file, you need to reference it in all your pages by including this tag in the <head> :

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


    (3/3) Enable one step op-in :

    Finally to set up the one step 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 "Enable one step opt-in"

     

    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.


     

    Quick integration vs. customization

    Our solution can be fully configured. You can legitimately configure it to create the most adapted process according to the look and feel of your website.
    See below an illustrated example used on our website in which we have customized some steps:


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

    This page intends to explicit some common use cases about the optout-to-optin customization

    Configuration

    To configure the optin-to-optout process for your application, go on our interface > Settings > Manage Applications > Edit your application. You will have a Plugins configuration parameter. Within the "push" property, you will be able to set this parameters:

    ParameterTypeDefaultDescription
    scenario<string>"none"

    an action automaticaly initiated as soon as the library 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 library 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 :

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

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

    position<string>"topRight"

    the position of the HTML alert. Available value :

    • "topLeft", "topCenter", "topRight"
    • "middleLeft", "middleCenter", "middleRight"
    • "bottomLeft", "bottomCenter", "bottomRight"  
    overlay<boolean>false

    If true, add a semi-transparent layer between your page and the alert. With this option activated, users won't be able to click on your page's elements

    (only applied on "modern" theme)

    reAskingDelay<number>24

    If the user clicks on the "close" button, or hasn't interacted with the alert in a previous page, this parameter defines the number of hours to wait before showing the HTML alert again.

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

    reAskingDelay2<number>24

    If the user clicks on the "deny" button, this parameter defines the number of days to wait before showing the HTML alert 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 :

    • "white"
    • "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

    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

    Misc.

    How do "reAskingDelays" work ?

    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

    Our solution 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

    • No labels