Getting started
Overview
After following the instructions below, your html will look approximately like this:
1. Style
The SDK comes with it's own stylesheet (1st line) and icon font (2nd line). All of the class and ids are prefixed with apm-
in order to prevent interference in the global scope.
Don't hesitate to contact us for style changes you would like to do.
If you wish to change the style yourself, read the instructions below:
SCSS methodologies
Our CSS is compiled from SCSS and is organized through the use of two methodologies: ITCSS and BEM.
ITCSS Architecture. This allows to have a clearer hierarchy and css priority (the lower the CSS is, the higher its priority) and is useful to prevent the use of
!important
. It consists in organizing the files in the following order:1-settings
2-tools
3-generic
4-elements
5-objects
6-components
7-themes
8-utilities (Trumps)
CSS class names follow the naming convention of BEM (Block__Element--Modifier). This convention may seem obscure at the beginning, but it allows for consistent class names.
.apm-page__button--state-success
.apm-page
: Block__button
: Element--state-success
: Modifier
Each HTML element will often have a general class name (shared by multiple elements on different pages) and a unique class (so that we can modify the style of this element only). This allows for both refactoring and detail work.
<img class="apm-gift__image apm-media__image" src="..."/>
apm-media__image
is a general class name andapm-gift__image
is the unique class.
SCSS variables
Our SCSS was written in a way so that the SDK can be customized by duplicating and modifying the file 1-settings/s-base.scss
. This file is a mastersheet of SCSS variables which are used in all of the other SCSS files. It is thus possible to change the look and feel of the SDK only by modifying this file. It is always possible to do fine-grain work by editing the SCSS lower in the hierarchy.
These SCSS variables also follow the BEM naming convention. This is an example of how SCSS variables are organized in 1-settings/s-base.scss
:
Generic variables (located on top, reused by variables below within s-base.scss).
ex:
$font-family--default: Arial;
Object variables
ex:
$button--default--font-family: $font-family--default;
Component variables
ex:
$welcome__button-connect--font-family: $button--default--font-family;
This hierarchy in the variables creates a cascade of reference, but allows to modify multiple elements related to each other, by changing just one variable.
Examples
$font-family--header
will change the font for all headers$color--primary
, since it is used by other SCSS variables or by the style directly, will modify button colors, the tab background colors, etc ...
2. Configuration (apmConfig
)
apmConfig
)In order for the SDK to work properly, you will need to add the following Javascript variable before loading it. It is possible to externalize this variable into it's own JS file, as long as it is called before the SDK.
How to generate clientSignature
clientSignature
In order to enforce a higher degree of security. Our SDK uses JSON Web Tokens (JWT) to encrypt requests sent to our server. In order to do this, 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). 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:
3. Translations (apmTranslations
)
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.
Note: If keys are missing, error logs will be printed in the browser's console, indicating which ones are missing.
4. The SDK
Insert the link to the SDK that we have provided to you here.
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.
Be sure to configure $modal--open-direction
and $notif-direction
in the SCSS to match the anchor's placement.
6. The SDK methods (apmApi
)
apmApi
)If all of the above was configured properly, you should now see the SDK sticker and have access to the global variable apmApi
.
userClientConnect
Connects the user.
Should be called right after you've logged in/registered a user.
Do not call this method on each page. The SDK keeps the user connected to appsmiles across webpages through the use of localStorage
.
Return value
Error
If invalid arguments
If already connected
If user has not accepted RGPD yet (will connect once it is)
userObject
Example
Connecting user John Doe with his email 'john.doe@mail.com' associated with the ID/token you gave him. The segments here must match with the definition appsmiles has, in this example case: {s = sexe: m = male, p = prime: 0 = false}
Example
Connecting user John Doe with his email 'john.doe@mail.com' associated with the ID/token you gave him. The segments here must match with the definition appsmiles has, in this example case: {s = sexe: m = male, p = prime: 0 = false}
createUserWithActions
Warning: This method is specific to certain scenarios. Contact us to know if you should use it.
Creates a user and rewards him with the given actions (validated by the appsmiles server). Note 1: Does not connect the user. Note 2: If user already exists, assigns the actions (does not create duplicate).
If the action uses 'rules and filters', you have to add the properties object in each action with the corresponding properties.
Return value
Error (see error message)
earnObject (last earn in list) and userObject
Example
Example with properties
userProperties
Only necessary when using our filter functionality.
Call these methods to update user properties. These user properties are stored permanently on a device (using localStorage). The keys and values must match with the filters established with appsmiles.
Return value The current userProperties
Example :
triggerAction
Tells our server that the user accomplished the given action after the SDK checks whether the user is allowed to do the action (frequency, filters, etc...).
The tags must match with the tagging plan established with appsmiles.
Return value: 1. Error (see error message) 2. earnObject and userObject
Example :
logOut
Logs a user out. This must be called when a user is logged out of your website. The SDK will revert to it's non-connected state.
Example :
getUser
Retrieves a user.
Special fields:
deviceStatus
("-1"
: Not set,"0"
: Animated,"1"
: Anonymous,"2"
: Opt out)connectionStatus
. ("0"
: Not connected,"1"
: Connected)
Example :
hideSticker
Hide SDK without stopping the service: triggerActions are sent and notifications are stored
showSticker
Show SDK (if previously hidden)
disableNotifications
Disable SDK notifications (earn notifications are stored for later display)
enableNotifications
Enable SDK notifications and show stored notifications
open
Open modal (on specified screen if parameter is given, or last loaded screen if not)
close
Close modal
Models
userObject
earnObject
Notice
Since the SDK uses WebStorage (localStorage & sessionStorage), please avoid clearing either storages. Clearing them will wipe user data, thus making the user look offline on our SDK, until
userClientConnect
is called again.
Browser support
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 with data from December 2018 on gs.statcounter.com
More
For any questions, bugs or requests, please contact us on Slack or via email.
Last updated