Integration

 
 Web Integration
​🚩
 You have the app's miles sticker up and running. 
Now you need to integrate the SDK deeper into your website so that your user can:
- 🧠
understand how the program works.
- 🔎
discover all the functionalities that you slaved away at developing !
- 🥕
be rewarded for consistently using your application's main features.
I. Connection 
1. Onboarding 
This onboarding subsection is solely for explaining, no coding necessary
Purpose
The first thing that the user will see when clicking on the app's miles banner is the onboarding.
The onboarding has two purposes:
​🎓
 Present and explain the program
​❓
 Ask the user for their consent to take part in the program
Onboarding buttons
There are up to 3 buttons on the onboarding.
The input of the user will affect the variable OPT_IN in the following way:
(default: APM_DEVICE_OPT_IN_NOT_SET)
​👍
 OK: ACCEPT
​⌚
 Later: NOT_SET
​👎
 Never: REFUSE
It is possible to force an optIn status during the connection (see dataConsentCode below)
Connected or non-connected
There can be two different onboardings: 
for non-connected users
for connected users
Both of these onboardings only appear if the user has not decided whether they want to opt in or not.
An onboarding only appears if the optIn value is NOT_SET. 
If you want to force the optIn and still wish to present the program, it is better to use tutorials or walkthroughs (both can be configured in our BackOffice and require no code).
2. Connect
Method: userClientConnect(...)
If the user already exists, connects him
If not, creates the account and connects him
Should be called right after you've logged in/registered a user to your own website.
Do not call this method on each page. The SDK keeps the user connected to appsmiles across webpages through the use of localStorage.
1
apmApi.userClientConnect(
2
  email: string, 
3
  partnerClientId: string, // your user's ID
4
  firstName: string, 
5
  lastName: string, 
6
  segments: JSON // deprecated
7
  dataConsentCode?: -1 | 0 | 1 // NOT_SET = -1, ACCEPT = 0, REFUSE = 1
8
  // Optional parameter that allows to set directly RGPD consent
9
)
Copied!
Return value
Success
Error
1
{
2
    user: userObject{}
3
}
Copied!
1
ApmError{}
Copied!
Possible reasons: 
If invalid arguments
If already connected
If user has not accepted RGPD yet (will connect once it is)
Example
Connecting user 'John Doe' with his email [email protected] associated with the ID/token you gave him.
1
apmApi.userClientConnect('[email protected]', '1326793', 'John', 'Doe', null, -1);
Copied!
You will almost always see a notification when the user gets connected
Did it work ?
If when you click on the sticker, or on the CTA button in the onboarding, you keep getting redirected to the loginPageUrl (that you configured in apmConfig), then that means the connection isn't working. Check the logs to see what's happening (Debugging).
Depending on your integration, if you click the sticker after a successful connection, you should either see an onboarding which, when you click the CTA button, leads you to one of the SDK's screen (account, daily challenge, etc...), or directly one of the SDK's screen.
3. Logout
Method: logOut()
Logs a user out.
This must be called when a user is logged out of your website.
The SDK will revert to its non-connected state.
Example
1
apmApi.logOut();
Copied!
II. Tagging plan
1. Send an action
Method: 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.
1
/**
2
 * Tells the appsmiles server that the user accomplished an action (trigger)
3
 * which awards points if the conditions are met.
4
 *
5
 * @param {string} tagId
6
 * @param {{[s: string]: string}} properties Optional, both keys and values MUST BE strings
7
 */
8
apmApi.triggerAction(
9
  tagId: string,
10
  properties?: {[s: string]: string}
11
);
Copied!
Return value
Success
Error
1
{
2
  earn: earnObject,
3
  user: userObject
4
}
Copied!
1
ApmError{}
Copied!
See error message
Example
1
// Write a review on a business
2
apmApi.triggerAction("writeReview");
Copied!
Example of the notification of a earn (customizable design/animation)
2. Actions with properties
If your tagging plan requires the use of filters, you may need to send properties with your action.
Call triggerAction with a second parameter to send a tag with properties
– property.key : Property keys must be strings and must be in the tagging plan (e.g. « zipcode », « establishment »).
– property.value : Property values must be strings. (e.g. « 33000 », « restaurant »).
You can associate multiple values for a given key by separating them with the pipe character: {establishment: "restaurant|hotel"}
1
// Write a review on a restaurant
2
apmApi.triggerAction("writeReview", {establishment: "restaurant"});
3
// Write a review on a restaurant in Paris
4
apmApi.triggerAction("writeReview", {establishment: "restaurant", location: "75000"});
5
// Write a review on a hotel/restaurant
6
apmApi.triggerAction("writeReview", {establishment: "restaurant|hotel"});
Copied!
A tag may have multiple versions configured in our BackOffice. 
This is an unlikely scenario, but as an example, sending the same tag and properties 3 times may match with a different version each time.
3. User properties
Only necessary when using our filter functionality.
Method: addUserProperties(...), removeUserProperties(...)
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.
1
apmApi.addUserProperties(
2
  userProperties: {[s: string]: string}
3
);
4
apmApi.removeUserProperties(
5
  userPropertyKeys: string[]
6
);
Copied!
Return value 
The current userProperties
1
{
2
  key1: "value1",
3
  key2: "value2"
4
}
Copied!
Example
1
apmApi.addUserProperties({location: "33130", bankCard: "true", gender: "male"});
2
// => {location: "33130", bankCard: "true", gender: "male"}
3
apmApi.removeUserProperties(["location", "gender"]);
4
// => {bankCard: "true"}
5
apmApi.removeUserProperties();
6
// => {}
Copied!
4. Deeplinks
It is possible to attach deeplinks to certain buttons (e.g. challenge of the day).
There are two types of deeplinks:
apm deeplinks (navigates to screen inside the modal)
https links
apm deeplinks
These must follow the schema apm://{screen}/{arg?}
Available deeplinks:
1
// Open modal on a specific screen
2
apm://screen_challenges
3
apm://screen_trophies
4
apm://screen_daily_challenge
5
apm://screen_cnil
6
apm://screen_cgu
7
apm://screen_mentions
8
apm://screen_helper
9
apm://screen_app_onboarding
10
apm://screen_app_mention
11
apm://screen_app_tutorial
12
apm://screen_how_works
13
apm://screen_page/{id}
14
apm://screen_form/{id}
15
apm://screen_barcode
16
apm://screen_burns
17
apm://screen_burn/{id}
18
apm://screen_earns
19
apm://screen_gifts
20
apm://screen_gift/{id}
21
apm://screen_infos
22
apm://screen_my_account
23
apm://screen_unsubscribe
24
apm://screen_levels
25
​
26
// Actions
27
apm://back
28
apm://closeBadge
29
apm://onboarding/ok // accepts RGPD (only if on onboarding)
30
apm://onboarding/later // closes onboarding (only if on onboarding)
31
apm://onboarding/never //  refuses RGPD (only if on onboarding)
32
apm://trigger_action/{tagId} // sends a tag
33
apm://trigger_action_back/{tagId} // same as above, but closes modal/interstitial
34
apm://trigger_game/{gameId} // launch a game
35
​
36
// Deprecating (replaced by above deeplinks)
37
apm://challenge
38
apm://menu
39
apm://gifts
40
apm://burns
41
apm://earns
42
apm://levels
43
apm://pages-mentions
44
apm://pages-onboarding
45
apm://gift/{id}
46
apm://burn/{id}
47
apm://close
Copied!
https links
If you want to redirect to a page in your website.
III. Advanced functions
- Controlling the UI
Method: hideSticker()
Hide SDK without stopping the service: triggerActions are sent and notifications are stored
1
apmApi.hideSticker();
Copied!
Method: showSticker()
Show SDK (if previously hidden)
1
apmApi.showSticker();
Copied!
Method: disableNotifications()
Disable SDK notifications (earn notifications are stored for later display)
1
apmApi.disableNotifications();
Copied!
Method: enableNotifications()
Enable SDK notifications and show stored notifications
1
apmApi.enableNotifications();
Copied!
Method: open(...)
Open modal (on specified screen if parameter is given, or last loaded screen if not)
(See the list of apmDeeplinks)
1
apmApi.open(apmDeeplink?: string);
Copied!
Method: close()
Close modal
1
apmApi.close();
Copied!
Config: tabs
To change the number or order of tabs,  you will need to modify multiple places:
apmConfig.tabs: {...}: sets which screen each tab leads to
apmTranslations.Tabs: {...}: sets the label under the icon
apmTranslations.Icons.Tabs: {...}: sets the icon
All of these are arrays, and must have the same number and order of items.
- Debugging 🐞
 
Logs
Debug logs are controlled with two keys in apmConfig:
1
apmConfig {
2
    ...
3
    enableLogs: true | false,
4
    logLevel: "verbose" | "debug" | "info" | "warn" | "error"
5
}
Copied!
And one method which can be used to change the logs after the initialization.
1
apmApi.resetLogger(
2
    enableLogs: true | false, 
3
    logLevel: "verbose" | "debug" | "info" | "warn" | "error"
4
);
Copied!
You can also use your browser's debug functionalities such as filtering logs by searching for 'appsmiles' or selecting the log level you wish to see.
- Retrieving user info
Method: getUser()
Retrieves a user.
Special fields:
deviceStatus ("-1": Not set, "0": Animated, "1": Anonymous, "2": Opt out)
connectionStatus. ("0": Not connected, "1": Connected)
Example :
1
apmApi.getUser();
2
/*
3
returns 
4
{
5
  "partnerClientId":"12345",
6
  "userToken":"c56aff3faca3ee9259600081eebbf83d1d0ba5a7",
7
  "email":"[email protected]",
8
  "firstName":"Tester",
9
  "mobileNumber": undefined,
10
  "gender":"0",
11
  "birthdate": undefined,
12
  "town": undefined,
13
  "status":"4", // the level of the user
14
  "segments": {"a": "1"}
15
  "infos": undefined,
16
  "userBalance":"28685", // totalEarn - points spent for gifts
17
  "userObsoleteBalance":"-1",
18
  "totalEarn":"28775"
19
  "deviceStatus":"0",
20
  "connectionStatus":"1",
21
}
22
*/
Copied!
- Retrieving levels
You can retrieve levels if you need certain information.
1
apmApi.getLevels();
2
[
3
  {
4
    color: "#ffffff", // Color, only for icons
5
    desc: "Vos premier pas",
6
    gradation: 5, // How many segments in the progression bar
7
    id: 1,
8
    illus: "\ue908", // The foreground illustration, can be an icon, image or lottie
9
    index: 0,
10
    label: "Débutant",
11
    middleground: "APMAnimationMiddlegroundLevel1", // Middleground illustration
12
    step: 0 // The number of points needed to reach this level
13
  }
14
]
Copied!
- Display user balance
If you want to display the user's current balance, use the apm-client__user-balance class (instead of fetching the info with apmApi.getUser()). The balance will automatically be updated after the sdk loads, and when the balance changes (e.g. after a triggerAction)
1
<span class="apm-client__user-balance"></span>
Copied!
- Creating a user with actions
Method: createUserWithActions(...)
This method is for very specific scenarios. Contact us to know if it's the right choice for your needs.
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.
1
apmApi.createUserWithActions(
2
  actions: Array<{tagID: string, properties?: {[code: string]: string}}>, // array of objects with the property 'tagID'
3
  email: string,
4
  partnerClientId: string,
5
  firstName: string,
6
  lastName: string,
7
  segments: any
8
)
Copied!
Return value
Success
Error
1
{
2
    earns: earnObject[],
3
    user: userObject{}
4
}
Copied!
1
ApmError{}
Copied!
Example
1
var actions = [
2
  {tagID: "tag1"},
3
  {tagID: "tag2"},
4
  {tagID: "tag3"},
5
];
6
apmApi.createUserWithActions(actions, "[email protected]", "987654321", "John", "Doe", undefined);
Copied!
Example with properties
1
var actions = [
2
  {tagID: "writeReview", properties: {city: "paris", establishment: "restaurant"}},
3
  {tagID: "writeReview", properties: {city: "paris", establishment: "hotel"}}
4
  {tagID: "writeReview", properties: {city: "brussels", establishment: "hotel"}},
5
];
6
apmApi.createUserWithActions(actions, "[email protected]", "987654321", "John", "Doe", undefined);
Copied!
- Other functions
Method: init()
This method is for very specific scenarios. To use it correctly, you need to add thewaitForInit key in the apmConfig and set it totrue. Contact us to know if it's the right choice for your needs
Example
1
apmApi.init()
Copied!
Method: triggerGame(...)
This method allow the client to launch a game.
1
apmApi.triggerGame({
2
  gameId: number, // the ID of the game, set in the BO
3
  displayMode?: string, // the display mode wanted. "INTERSTITIAL" or "BIGBADGE"
4
  onGameFinished?: Function, // a function called at the end of the game
5
})
Copied!
Example
1
apmApi.triggerGame({
2
    gameId : 147,
3
    displayMode: "INTERSTITIAL"
4
})
Copied!
External Libraries
The SDK is able to use certain libraries for specific features. If you need any of those features, you will need to load these libraries yourself, and make sure they are loaded before appsmiles-sdk.js .
1. Lottie
Lottie (https://airbnb.design/lottie/) is a library that can play "Adobe After Effects" animations in your browser and mobile application by reading a JSON file.
We have made it possible to incorporate these animations in many places and elements within the SDK:
Sticker
Full screen notification
Mission background
"Page" background (screen that displays a page loaded from the BackOffice, e.g. onboarding,  interstitial)
Challenges screen (gamification)
Trophies screen (gamification)
2. JsBarcode
JsBarcode (https://github.com/lindell/JsBarcode) allows to generate a barcode image from a code. If any of the gifts you wish to make available needs to be rendered as a barcode, you will need to load this library before appsmiles-sdk.js is loaded.
Models
userObject
1
class userObject {
2
  partnerClientId: string | undefined = "1234321"; 
3
  userToken: string | undefined = "9abaa65989758d59fa560f61112a418850f32603"; 
4
  email: string | undefined = "[email protected]"; 
5
  firstName: string | undefined = "John"; 
6
  lastName: string | undefined = "Doe"; 
7
  mobileNumber: string | undefined = "0612345678"; 
8
  gender: string | undefined = "0"; 
9
  birthdate: string | undefined = ""; 
10
  town: string | undefined = ""; 
11
  status: string | undefined = "1"; // level 
12
  segments: string | undefined = ""; 
13
  infos: string | undefined;
14
  deviceStatus: string | undefined = "0"; // -1: NOT_SET, 0: OK, 1: ANONYMOUS (control group), 2: OPT_OUT
15
  userBalance: string | undefined = "40";
16
  userObsoleteBalance: string | undefined;
17
  totalEarn: string | undefined = "240";
18
}
Copied!
earnObject
1
class earnObject {
2
  earnID: string | undefined = "137189";
3
  earnValue: string | undefined = "40";
4
  partnerLabel: string | undefined = "nom de la compagnie";
5
  earnDate: string | undefined = "12/09/2018";
6
  earnLabel: string | undefined = "En créant votre compte";
7
}
Copied!
Quickstart
Release notes
Last modified 11mo ago