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

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

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

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.

2. Connect

Method: userClientConnect(...)

Connects the user. 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.

apmApi.userClientConnect(
  email: string, 
  partnerClientId: string, // your user's ID
  firstName: string, 
  lastName: string, 
  segments: JSON // deprecated
  dataConsentCode?: -1 | 0 | 1 // NOT_SET = -1, ACCEPT = 0, REFUSE = 1
  // Optional parameter that allows to set directly RGPD consent
)

Return value

{
    user: userObject{}
}

ApmError{}

Example

Connecting user 'John Doe' with his email john.doe@mail.com associated with the ID/token you gave him.

apmApi.userClientConnect('john.doe@mail.com', '1326793', 'John', 'Doe', null, -1);

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

apmApi.logOut();

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.

/**
 * Tells the appsmiles server that the user accomplished an action (trigger)
 * which awards points if the conditions are met.
 *
 * @param {string} tagId
 * @param {{[s: string]: string}} properties Optional, both keys and values MUST BE strings
 */
apmApi.triggerAction(
  tagId: string,
  properties?: {[s: string]: string}
);

Return value

{
  earn: earnObject,
  user: userObject
}

ApmError{}

Example

// Write a review on a business
apmApi.triggerAction("writeReview");

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"}

// Write a review on a restaurant
apmApi.triggerAction("writeReview", {establishment: "restaurant"});
// Write a review on a restaurant in Paris
apmApi.triggerAction("writeReview", {establishment: "restaurant", location: "75000"});
// Write a review on a hotel/restaurant
apmApi.triggerAction("writeReview", {establishment: "restaurant|hotel"});

3. User properties

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.

apmApi.addUserProperties(
  userProperties: {[s: string]: string}
);
apmApi.removeUserProperties(
  userPropertyKeys: string[]
);

Return value

The current userProperties

{
  key1: "value1",
  key2: "value2"
}

Example

apmApi.addUserProperties({location: "33130", bankCard: "true", gender: "male"});
// => {location: "33130", bankCard: "true", gender: "male"}
apmApi.removeUserProperties(["location", "gender"]);
// => {bankCard: "true"}
apmApi.removeUserProperties();
// => {}

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:

// Open modal on a specific screen
apm://screen_challenges
apm://screen_trophies
apm://screen_daily_challenge
apm://screen_cnil
apm://screen_cgu
apm://screen_mentions
apm://screen_helper
apm://screen_app_onboarding
apm://screen_app_mention
apm://screen_app_tutorial
apm://screen_how_works
apm://screen_page/{id}
apm://screen_form/{id}
apm://screen_barcode
apm://screen_burns
apm://screen_burn/{id}
apm://screen_earns
apm://screen_gifts
apm://screen_gift/{id}
apm://screen_infos
apm://screen_my_account
apm://screen_unsubscribe
apm://screen_levels
​
// Actions
apm://back
apm://closeBadge
apm://onboarding/ok // accepts RGPD (only if on onboarding)
apm://onboarding/later // closes onboarding (only if on onboarding)
apm://onboarding/never //  refuses RGPD (only if on onboarding)
apm://trigger_action/{tagId} // sends a tag
apm://trigger_action_back/{tagId} // same as above, but closes modal/interstitial
​
// Deprecating (replaced by above deeplinks)
apm://challenge
apm://menu
apm://gifts
apm://burns
apm://earns
apm://levels
apm://pages-mentions
apm://pages-onboarding
apm://gift/{id}
apm://burn/{id}
apm://close

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

apmApi.hideSticker();

Method: showSticker()

Show SDK (if previously hidden)

apmApi.showSticker();

Method: disableNotifications()

Disable SDK notifications (earn notifications are stored for later display)

apmApi.disableNotifications();

Method: enableNotifications()

Enable SDK notifications and show stored notifications

apmApi.enableNotifications();

Method: open(...)

Open modal (on specified screen if parameter is given, or last loaded screen if not) (See the list of apmDeeplinks)

apmApi.open(apmDeeplink?: string);

Method: close()

Close modal

apmApi.close();

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.

Config: notifications

You can configure the notification template with the notifications key in apmConfig. For the GIF below, the following config was set:

apmConfig.notifications = {
    global: {
      template: "notif",
      foregroundGraphicResourceKey: undefined,
      onClick: "apm://default"
    },
    trophy: {
      template: "notif--fullscreen",
      foregroundGraphicResourceKey: "APMAnimWinTrophy", // Set in APM BackOffice
    }
  }

- Debugging 🐞

Logs

Debug logs are controlled with two keys in apmConfig:

apmConfig {
    ...
    enableLogs: true | false,
    logLevel: "verbose" | "debug" | "info" | "warn" | "error"
}

And one method which can be used to change the logs after the initialization.

apmApi.resetLogger(
    enableLogs: true | false, 
    logLevel: "verbose" | "debug" | "info" | "warn" | "error"
);

- 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 :

apmApi.getUser();
/*
returns 
{
  "partnerClientId":"12345",
  "userToken":"c56aff3faca3ee9259600081eebbf83d1d0ba5a7",
  "email":"test@appsmiles.fr",
  "firstName":"Tester",
  "mobileNumber": undefined,
  "gender":"0",
  "birthdate": undefined,
  "town": undefined,
  "status":"4", // the level of the user
  "segments": {"a": "1"}
  "infos": undefined,
  "userBalance":"28685", // totalEarn - points spent for gifts
  "userObsoleteBalance":"-1",
  "totalEarn":"28775"
  "deviceStatus":"0",
  "connectionStatus":"1",
}
*/

- Retrieving levels

You can retrieve levels if you need certain information.

apmApi.getLevels();
[
  {
    color: "#ffffff", // Color, only for icons
    desc: "Vos premier pas",
    gradation: 5, // How many segments in the progression bar
    id: 1,
    illus: "\ue908", // The foreground illustration, can be an icon, image or lottie
    index: 0,
    label: "Débutant",
    middleground: "APMAnimationMiddlegroundLevel1", // Middleground illustration
    step: 0 // The number of points needed to reach this level
  }
]

- 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)

<span class="apm-client__user-balance"></span>

- Creating a user with actions

Method: createUserWithActions(...)

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.

apmApi.createUserWithActions(
  actions: Array<{tagID: string, properties?: {[code: string]: string}}>, // array of objects with the property 'tagID'
  email: string,
  partnerClientId: string,
  firstName: string,
  lastName: string,
  segments: any
)

Return value

{
    earns: earnObject[],
    user: userObject{}
}

ApmError{}

Example

var actions = [
  {tagID: "tag1"},
  {tagID: "tag2"},
  {tagID: "tag3"},
];
apmApi.createUserWithActions(actions, "sdkweb@appsmiles.fr", "987654321", "John", "Doe", undefined);

Example with properties

var actions = [
  {tagID: "writeReview", properties: {city: "paris", establishment: "restaurant"}},
  {tagID: "writeReview", properties: {city: "paris", establishment: "hotel"}}
  {tagID: "writeReview", properties: {city: "brussels", establishment: "hotel"}},
];
apmApi.createUserWithActions(actions, "sdkweb@appsmiles.fr", "987654321", "John", "Doe", undefined);

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

class userObject {
  partnerClientId: string | undefined = "1234321"; 
  userToken: string | undefined = "9abaa65989758d59fa560f61112a418850f32603"; 
  email: string | undefined = "a@b.com"; 
  firstName: string | undefined = "John"; 
  lastName: string | undefined = "Doe"; 
  mobileNumber: string | undefined = "0612345678"; 
  gender: string | undefined = "0"; 
  birthdate: string | undefined = ""; 
  town: string | undefined = ""; 
  status: string | undefined = "1"; // level 
  segments: string | undefined = ""; 
  infos: string | undefined;
  deviceStatus: string | undefined = "0"; // -1: NOT_SET, 0: OK, 1: ANONYMOUS (control group), 2: OPT_OUT
  userBalance: string | undefined = "40";
  userObsoleteBalance: string | undefined;
  totalEarn: string | undefined = "240";
}

earnObject

class earnObject {
  earnID: string | undefined = "137189";
  earnValue: string | undefined = "40";
  partnerLabel: string | undefined = "nom de la compagnie";
  earnDate: string | undefined = "12/09/2018";
  earnLabel: string | undefined = "En créant votre compte";
}