Integration

Last updated 2 months ago

Connect the app's miles® SDK to all of your website's features to start driving your users and build retention.

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

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

Success
Error
{
user: userObject{}
}
ApmError{}

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 john.doe@mail.com associated with the ID/token you gave him.

apmApi.userClientConnect('john.doe@mail.com', '1326793', 'John', 'Doe', null, -1);
You will almost always see a notification when the user gets connected

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

Success
Error
{
earn: earnObject,
user: userObject
}
ApmError{}

See error message

Example

// Write a review on a business
apmApi.triggerAction("writeReview");
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 »).

// 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"});

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.

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"]);
// => {bankCardSaved: "true"}
apmApi.removeUserProperties();
// => {}

It is possible to associate 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

These must follow the schema apm://{screen}/{arg?}

Available deeplinks:

apm://challenge
apm://menu
apm://gifts
apm://burns
apm://earns
apm://levels
apm://pages-mentions
apm://pages-onboarding
apm://gift/401
apm://burn/3
apm://close
apm://back
apm://onboarding/ok
apm://onboarding/later
apm://onboarding/never

If you want the deeplink to prevent the original action behind the button, you can add a $ at the end.

apm://gifts$
apm://gift/401$

If you want to redirect to a page in your website.

For security reasons, http links are not supported

III. Advanced functions

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

apmApi.open(screenName?: "challenge" | "menu" | "gifts" | "burns" | "earns" | "levels" | "pages-mentions" | "pages-onboarding-anonymous" | "pages-onboarding-connected");

Method: close()

Close modal

apmApi.close();

2. Debug logs 🐞

Debug logs are controlled with two keys in apmConfig:

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

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.

3. User

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",
}
*/

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

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

Success
Error
{
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);

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