Quickstart

Follow these steps to have a basic integration of the SPLIO / D-AIM SDK on your website.

Web Quickstart

Introduction

Splio / D-AIM offers you several libraries to simply the integration of our API into your systems. For a web integration, we provide you two libraries :

ApmService : This library will handle all the Http requests and the libraries states. It simplified all the interaction you can have with our APIs
ApmView: This library is optional. It handle all the UI

Summary and steps

Integration this new version of the Splio / D-AIM library is very simple. You just need to follow thoses 5 steps :

Prepare configuration
Import the ApmStyle.css
Import the module ApmService.js
Import the module ApmView.js [OPTIONAL]

Overview

After following the instructions below, your html will look approximately like this:

<html>

<head>
  ...
  <link rel="stylesheet" type="text/css" href="apmStyle.css" />
  ...
</head>

<body>
  ...
  <div id="d-engage"></div>
  ...

  ...
  <script>
    var apmConfig = {...};
  </script>
  <!-- or <script src="path/to/apmConfig.js"></script> -->

  <script src="apmService.js"></script>
  <script src="apmView.js"></script>
  ...
</body>

</html>

I. Prerequisite

We generally create a release personalized for your needs. Contact us to get the SDK files and we will provide you all the files needed.

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 (apmStyle.css)

One file:

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

<head>
    ...
    <link rel="stylesheet" type="text/css" href="path/to/style.css" />
</head>

Don't hesitate to contact us if you would like style changes

You can also overwrite the sdk style if it is needed.

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

var window.ApmConfig = {    
    // REQUIRED
    apiBaseUrl: "[Required] {string} URL of the D-Engage 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",
    lang: "[Required] {string} Language in which the SDK should be. 2 letter country code.",
    partnerId: "[Required] {string} ID of the partner in the d-engage back-office",
    webStorageEncryptionAlgorithm: "[Required] {number} always 0",
    appId: "[Required] {string} ID of the app (a partner can have several apps, web, mobile, etc...)"
    progTTL: "[Required] {number} time in millisecond between two automatic update of the program",
    
    // OPTIONAL
    waitForInit: "[Optional] {boolean} If needed, the sdk can be initialized by the client when he decided, with the ApmView.init() method. Default is false",
    trackingId: "[Optional] {string} Google Analytics ID"
}

We will provide you the configuration file you will need

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.

HmacSHA256( // using CryptoJS library
  timestamp: string, // ! Very important for it to be a STRING
  partnerSecret: string)
  .toString()
  .substring(0, 15)
  .toUpperCase();

<?php

$partnerSecret = <PARTNER_SECRET>;
$clientSignatureTimestamp = (new DateTime())->getTimestamp();
$rawClientSignature = hash_hmac('sha256', $clientSignatureTimestamp, $partnerSecret);
$clientSignature = strtoupper(substr($rawClientSignature, 0, 15));
// TODO: make $clientSignatureTimestamp and $clientSignature available to the client

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:

<script>
    window.ApmConfig.clientSignature = <clientSignature>;
    window.ApmConfig.clientSignatureTimestamp = <clientSignatureTimestamp>;
</script>

4. The Service SDK (ApmService.js)

This is the main JS file, containing the logic. This SDK is requiered, but it has no UI.

This step can be the last one if you want to handle by yourself all the UI

<script src="apmService.js"></script>

5. The View SDK (ApmView.js) [OPTIONAL]

This is the UI SDK. It has to be initialized and imported after the ApmService SDK.

<script src="apmView.js"></script>

6. HTML anchor [OPTIONAL]

The View 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.

If you have set the log level to "debug" inside the back-office, here is what you should have inside your console :

PreviousWeb NextIntegration

Last updated 2 years ago