Quickstart

 
 Web Quickstart
Conditions and minimum requirements
Supported on all browsers except IE9 and below.
Desktop:
Browser
Chrome
Edge
Firefox
IE
Opera
Safari
Oldest version supported
5
all
4
9
10.5
5
Support coverage
100.00%
100.00%
99.37%
94.49%
100.00%
100.00%
Mobile:
Browser
Android WebView
Chrome
Edge
Firefox
Opera
Safari
Samsung Internet
Oldest version supported
all
all
all
4
all
all
all
Support coverage
100.00%
100.00%
100.00%
99.37%
100.00%
100.00%
100.00%
Stats calculated based on data on gs.statcounter.com from December 2018
100% compatibility is possible, but implies adding quite a few additional polyfills. We opted for a leaner SDK instead of supporting old and mostly unused browser versions.
Our SDK weighs around 450kb.
Overview
After following the instructions below, your html will look approximately like this:
1
<html>
2
​
3
<head>
4
  ...
5
  <link rel="stylesheet" type="text/css" href="path/to/style.css" />
6
  ...
7
</head>
8
​
9
<body>
10
  ...
11
  <div id="d-engage"></div>
12
  ...
13
​
14
  ...
15
  <script>
16
    var apmConfig = {...};
17
  </script>
18
  <!-- or <script src="path/to/apm-config.js"></script> -->
19
​
20
  <script src="path/to/d-engage.js"></script>
21
  ...
22
</body>
23
​
24
</html>
Copied!
​
Vocabulary
I. Installation
We generally create a release personalized for your needs. Contact us to get the SDK files.
In order for everything to work properly, we require that the folder we provide be integrated as-is. Do not move the files inside, or some paths will be broken.
II. Configuration
There are 3 different HTML tags to add to your html for the SDK. They must be put in the following order:
1. Style (style.css)
One file:
style.css
The SDK comes with it's own stylesheet (1st file). All of the class and ids are prefixed with d-e- in order to prevent interference in the global scope.
1
<head>
2
    ...
3
    <link rel="stylesheet" type="text/css" href="path/to/style.css" />
4
</head>
Copied!
Don't hesitate to contact us if you would like style changes
If instead you see squares instead of icons, this means that the icon font wasn't properly configured in the BO.  Same thing if you see raw text appearing with no style (temporarily, or permanently) where the sticker is supposed to be. This can often happen when files are loaded asynchronously, in which case you have to load these files synchronously in respect to each other (see Ajax and other asynchronous integrations).
​
 
 
(left) No icons (right) No SDK CSS
2. Configuration (apmConfig)
There are many configuration options, some required and others optionals. There are also configuration to help during the development process.
You can externalize this variable into its own JS file, as long as it is called before the main JS file
1
var apmConfig = {    
2
    // REQUIRED
3
    apiBaseUrl: "[Required] {string} URL of the appsmiles API, modify to point to sandbox or prod environment",
4
    trackingId: "[Required] {string} Google Analytics ID",
5
    clientSignature: "[Required] {string} Signature created with HmacSHA256(timestampString, partnerSecretString).toString().substring(0, 15).toUpperCase();",
6
    clientSignatureTimestamp: "[Required] {number} Timestamp used for client signature creation",
7
    lang: "[Required] {string} Language in which the SDK should be. 2 letter country code.",
8
    partnerId: "[Required] {string} ID of the partner in the d-engage back-office",
9
    webStorageEncryptionAlgorithm: "[Required] {number} always 0",
10
    appId: "[Required] {string} ID of the app (a partner can have several apps, web, mobile, etc...)"
11
    progTTL: "[Required] {number} time in millisecond between two automatic update of the program",
12
    
13
    // OPTIONAL
14
    waitForInit: "[Optional] {boolean} If needed, the sdk can be initialized by the client when he decided, with the apmApi.init() method. Default is false"
15
}
Copied!
3. Generating the clientSignature(required)
Among the required options in apmConfig, there is the clientSignature. You will find below what you need to know to generate this signature.
In order to enforce a higher degree of security, our SDK uses JSON Web Tokens (JWT) to encrypt requests sent to our server.
To do that, we need a signature. However, since Javascript code is completely visible to the client, the signature must be generated by your server.
This signature must be generated server-side, in the language your server uses (e.g. PHP, Ruby). It must not be calculated client-side (browser).
Signature type: HMAC SHA-256.
Arguments: timestamp (current time) and the partnerSecret key that we will have provided to you.
Post-processing: Keep first 15 characters and convert to uppercase.
JS
PHP
1
HmacSHA256( // using CryptoJS library
2
  timestamp: string, // ! Very important for it to be a STRING
3
  partnerSecret: string)
4
  .toString()
5
  .substring(0, 15)
6
  .toUpperCase();
Copied!
1
<?php
2
​
3
$partnerSecret = <PARTNER_SECRET>;
4
$clientSignatureTimestamp = (new DateTime())->getTimestamp();
5
$rawClientSignature = hash_hmac('sha256', $clientSignatureTimestamp, $partnerSecret);
6
$clientSignature = strtoupper(substr($rawClientSignature, 0, 15));
7
// TODO: make $clientSignatureTimestamp and $clientSignature available to the client
Copied!
The signature must be regenerated on each page load. The timestamp is only valid 10 minutes.
Now on the client side, you add clientSignature and clientSignatureTimestamp in the apmConfig object:
1
<script>
2
    apmConfig.clientSignature = <clientSignature>;
3
    apmConfig.clientSignatureTimestamp = <clientSignatureTimestamp>;
4
</script>
Copied!
4. The SDK (d-engage.js)
This is the main JS file, containing the logic, and UI elements (except the styling).
1
<script src="path/to/d-engage.js"></script>
Copied!
5. HTML anchor
The SDK will look for a div with the id 'd-engage' like so : <div id="d-engage"></div>.
Place this anchor where you wish the button to appear.
The design of the sticker, the placement of the modal and the direction of the notifications are all configured in the style file.
III. Initialization
The SDK initializes itself automatically when the 4. The SDK script tag is executed.
Hurray !
Ajax and other asynchronous integrations
If you are not loading through HTML tags, make sure that the order is respected.
The most important is that the stylesheets and config  are fully loaded before  appsmiles-sdk.js is loaded.
If the order is not respected, you may see:
A bunch of text appearing where the sticker is supposed to be (CSS was not loaded in time)
Console errors about apmConfig
Here is a very basic example of asynchronous loading in one of the correct order:
style.css > apm-config.js > d-enagage.js
1
var loadApm = function () {
2
  var cssSdk = document.createElement('link');
3
  cssSdk.rel = "stylesheet";
4
  cssSdk.type = "text/css";
5
  cssSdk.href = "./style.css";
6
  cssSdk.onload = function () {
7
    var scriptConfig = document.createElement('script');
8
    scriptConfig.src = "./apm-config.js";
9
    scriptConfig.onload = function () {
10
      window['apmConfig'].clientSignature = createClientSignature();
11
      var scriptSdk = document.createElement('script');
12
      scriptSdk.src = "./d-engage.js";
13
      document.head.appendChild(scriptSdk);
14
    }
15
    document.head.appendChild(scriptConfig);
16
  }
17
  document.head.appendChild(cssSdk);
18
}
19
​
20
loadApm();
Copied!