Quickstart

Last updated 2 months ago

Follow these steps to have a basic integration of the app's miles® SDK on your website.

  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 350kb.
Overview
After following the instructions below, your html will look approximately like this:
<html>
​
<head>
  ...
  <link rel="stylesheet" type="text/css" href="path-to-domain-name/3.0/css/appsmiles-sdk.css" />
  <link rel="stylesheet" type="text/css" href="path-to-domain-name/3.0/css/appsmiles-icons.css" />
  ...
</head>
​
<body>
  ...
  <div id="apm-sticker"></div>
  ...
​
  ...
  <script>
    var apmConfig = {...} // Required
  </script>
  <!-- or <script src="path/to/apm-config.js"></script> -->
​
  <script>
    var apmTranslations = {...} // Optional
  </script>
  <!-- or <script src="path/to/apm-translations.js"></script> -->
​
  <script src="path-to-domain-name/3.0/js/appsmiles-sdk.js"></script>
  ...
</body>
​
</html>
​
Vocabulary
I. Installation
You can find our public releases at:
Add links for CDN resources
II. Configuration
There are 5 different tags to add to your html for the SDK. They must be put in the following order:
1. Style
Two files:
appsmiles-sdk.css
appsmiles-icons.css
The SDK comes with it's own stylesheet (1st file) and icon font (2nd file). All of the class and ids are prefixed with apm- in order to prevent interference in the global scope.
<head>
    ...
    <link rel="stylesheet" type="text/css" href="path-to-domain-name/{version}/css/appsmiles-sdk.css" />
    <link rel="stylesheet" type="text/css" href="path-to-domain-name/{version}/css/appsmiles-icons.css" />
</head>
Don't hesitate to contact us if you would like style changes
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
<script>
      var apmConfig = {    
      
        // Required
        apiBaseUrl: "[Required] {string} URL of the appsmiles API, modify to point to sandbox or prod environment",
        clientSignature: "[Required] {string} Signature created with HmacSHA256(timestampString, partnerSecretString).toString().substring(0, 15).toUpperCase();",
        clientSignatureTimestamp: "[Required] {number} Timestamp used for client signature creation",
        defaultSticker: "[Required] {string} Absolute or relative url of the image to use for the default sticker",
        lang: "[Required] {string} Language in which the SDK should be. 2 letter country code.",
        mediaBaseUrl: "[Required] {string} URL of the appsmiles media folder, modify to point to sandbox or prod environment",
        openFrom: "[Required] {string} Direction from which the SDK should open (N, NNE, NE, ENE, E, ESE, SE, SSE, S, SSW, SW, WSW, W, WNW, NW, NNW, C)",
        partnerId: "[Required] {string} ID of the partner in the appsmiles back-office",
        ribbonDirection: "[Required] {string} Direction towards which the notification ribbon should extend (N, E, S, W)",
        closeIconPosition: "[Required] {string} Position of the close icon. Same values than openFrom. Keep empty field (default) to hide."
        
        // Conditional (scenario specific)
        partnerClientId: "[Conditional] {string} ID of the user according to the integrator's database",
        segments: "[Conditional] {JSON} JSON of the user's segment",
        showBalanceInSticker: "[Conditional] {boolean} Whether to show the user's balance in the sticker",
        
        // Optional
        loginPageUrl: "[Optional] {string} Url of the sign-in/sign-up page",
        hideStickerIfOptOut: "[Optional] {boolean} Hide sticker if user chooses to opt out. Default is false. Consider to integrate a way for the user to opt back in if you choose to set it to true",
        hideStickerIfSdkOff: "[Optional] {boolean} Hide sticker if SDK is set to OFF or if non-functional. Default is false",
        timeoutDuration: "[Optional] {number} Number of seconds to wait before http requests enter timeout",
        notificationDuration: "[Optional] {number} Duration in ms of the notification (including animation)",
        generosityBufferPolicy: "[Optional] {number} Policy as to how to handle triggerActions when user is not connected. -1: always discard, -2: keep after userClientConnect is called (while waiting for server response or RGPD opt-in), 0: always keep, x > 0: keep only actions in the last x seconds after user connected.",
        stickerNotificationBadgePolicy: "[Optional] {number} Policy as to when to show the notification badge on the sticker. -1: never show, 0: always show, 1: show when new content available"
        
        // Development
        openAndLoad: "[Dev] {string} Have modal open on a specific screen on refresh (welcome, challenge, menu, gifts, gift, burns, burn, earns, levels, pages-mentions, pages-onboarding-anonymous, pages-onboarding-connected)",
        overrideProgTTL: "[Dev] {number} Override progTTL (automatic refresh interval), in seconds",
        alwaysNewAction: "[Dev] {boolean} Always get a new action to suggest to the user (otherwise, only new action if user completed the current one)",
        clearApmCacheOnRefresh: "[Dev] {boolean} Clear localStorage and sessionStorage for any apm keys",
        resetOptInOnRefresh: "[Dev] {boolean} Reset opt in on refresh to see onboarding with buttons everytime",
        enableLogs: "[Dev] {boolean} Enable logs, overrides the appsmiles debugMode setting",
        logLevel: "[Dev] {string} Set log level (verbose, debug, info, warn, error)",
        forceCookies: "[Dev] {boolean} NOT IMPLEMENTED YET. Force use of cookies instead of WebStorage (if SDK should appear across sub domains)",
        forceRefresh: "[Dev] {boolean} Bypass the waiting time (default: 5 minutes) between API checks on page reload",
        forceDeeplink: "[Dev] {string} Force the deeplink button to appear and to redirect to link in variable",
      }
</script>
How to generate 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, AngularJS, Ruby). It must not be calculated client-side (browser).
You then add the generated string in the apmConfig.clientSignature object.
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.
Javascript example
JS
Todo:PHP
Todo:Ruby
HmacSHA256( // using CryptoJS library
  timestamp: string, // ! Very important for it to be a STRING
  partnerSecret: string)
  .toString()
  .substring(0, 15)
  .toUpperCase();
​
​
3. Translations (apmTranslations)
Our SDK comes with a default French translation. If you wish to change it, or add more languages, you can use the global variable apmTranslations so that the SDK can access them, and use apmConfig.lang to point to the correct translation.
See the default translations.js file provided.
<script src="path-to-domain-name/{version}/apm-translations.js"></script>
If keys are missing, error logs will be printed in the browser's console, indicating which ones are missing.
4. The SDK
This is the main JS file, containing the logic, and UI elements (except the styling).
<script src="path-to-domain-name/{version}/appsmiles-sdk.js"></script>
5. HTML anchor
The SDK will look for a div with the id 'apm-sticker' like so : <div id="apm-sticker"></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 integration
Work In Progress

Developers - Previous

Web

Integration

Quickstart

Conditions and minimum requirements

Overview

Vocabulary

I. Installation

II. Configuration

1. Style

2. Configuration (`apmConfig`)

How to generate `clientSignature`(required)

3. Translations (`apmTranslations`)

4. The SDK

5. HTML anchor

III. Initialization

Ajax integration

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%

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%

Quickstart

Conditions and minimum requirements

Overview

​

Vocabulary

I. Installation

II. Configuration

1. Style

2. Configuration (apmConfig)

How to generate clientSignature(required)

3. Translations (apmTranslations)

4. The SDK

5. HTML anchor

III. Initialization

Ajax integration

2. Configuration (`apmConfig`)

How to generate `clientSignature`(required)

3. Translations (`apmTranslations`)