Integration

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

Android Integration

🚩 You now have the app's miles banner up and running.

Next, you need to integrate the SDK deeper into your application 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

Skip to the Connect section if you intend to have everyone participate in the program by default

An onboarding example

Purpose

The first thing that the user will see when clicking on the app's miles banner is the onboarding.

This onboarding has two purposes:

• 🎓 Present and explain the program
• ❓ Ask the user their consent to take part in the program

Onboarding choices

There are up to 3 buttons on the onboarding, and you must attach a listener in order to redirect the user depending on their input.

The input of the user will affect the variable OPT_IN in the following way: (default: APM_DEVICE_OPT_IN_NOT_SET)

• 👍 OK: APM_DEVICE_OPT_IN_ACCEPT
• ⌚ Later: APM_DEVICE_OPT_IN_NOT_SET
• 👎 Never: APM_DEVICE_OPT_IN_REFUSE

Example with AbstractActivity's lifecycle.

public class AbstractActivity extends FragmentActivity implements APMDeeplinkListener {
​
    @Override
    protected void onResume() {
        super.onResume();
        // Start listening
        APMDeeplinkUtils.getInstance().addListener(this);
    }
​
    @Override
    protected void onPause() {
        super.onPause();
        // Stop listening
        APMDeeplinkUtils.getInstance().removeListener(this);
    }
​
    @Override
    public void apmDeeplinkOnboardingButtonOkClicked() {
        // User clicked "OK" -> "I want to participate".
        // TODO: If user not connected, redirect to login/create-account page.
        // Nothing to do if user connected
    }
​
    @Override
    public void apmDeeplinkOnboardingButtonLaterClicked() {
        // User clicked "Later" -> "I'll decide later".
        // The SDK will continue showing the onboarding when clicking the banner
        // Nothing to do here in general
    }
​
    @Override
    public void apmDeeplinkOnboardingButtonNeverClicked() {
        // User clicked "Never" => "Stop asking me, hide the banner"
        // Note: The user may change his mind, and it is recommended to have a button
        // that allows the user to get back in the program
        // TODO: (Optional) You can redirect to the page with that "Get back in the program" button
        // (with a little message saying "You can always change your mind by clicking this button")
    }
    
    @Override
    public void apmDeeplinkActionButtonGoClicked(String url) {
        //Not used for onboarding
    }
    
    @Override
    public void apmDeeplinkClicked(String url) {
        //Not used for onboarding
    }
}

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

In order to offer a seamless experience, app's miles doesn't have a login or create-account page. The login/create-account process for app's miles is parallel to yours.

APMUIServicesUser.userClientConnect()

This method can both connect and create an account:

• If an app's miles account already exists with the given userID, the method signs them in.

• If no account exists, the method will automatically create their account and sign them in.

This method needs : « email », « userID » and « optIn » – « email » is the email of user – « userID » is a unique identifier in your database – « optIn » is the RGPD OptIn (see more below)

If you don’t want give the email, you can build an encrypted email 🔒 with the userID: {userID}@{your-company-name}.com (e.g. [e-mail])

String email = editTextEmail.getText().toString(); //Required
String userId = editTextUserId.getText().toString(); //Required
​
//optIn, APM_DEVICE_OPT_IN_NOT_SET, APM_DEVICE_OPT_IN_REFUSE, APM_DEVICE_OPT_IN_ACCEPT 
Integer optIn = APMServicesConfig.APM_DEVICE_OPT_IN_ACCEPT; //Required
​
APMUIServicesUser.userClientConnect(email, userId, optIn, new APMUserConnectListener() {
    @Override
    public void userConnectSuccess(APMUser user) {
        Log.e("Test", user + " connected !");
    }
​
    @Override
    public void failure(APMException exception) {
        Log.e("Test", "error : "+exception);
    }
});

3. Logout

The same way the login process is parallel to yours, so is the logout.

APMUIServicesUser.userLogout()

APMUIServicesUser.userLogout(this, new APMUserLogoutListener() {
    @Override
    public void userLogoutSuccess() {
        Toast.makeText(RegisterActivity.this, "Logout success !", Toast.LENGTH_SHORT).show();
    }

    @Override
    public void failure(APMException exception) {
        Toast.makeText(RegisterActivity.this, exception.errorMessage, Toast.LENGTH_SHORT).show();
    }
});

II. Tagging plan

1. Send an action

In order to reward the user for an action, you need to place triggers in your application. You will need to follow the Tagging plan that your marketing team created with us.

Be careful with the spelling, an extra character like a 's' will change the tag

Call the method triggerAction to send a tag:

APM.sharedInstance(this).triggerAction("display_product"); 
// this --> Context
// "display_product" --> actionName

Make sure to test each action by looking at the logs, especially for actions that are more complex

Earn animation

2. Action 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 »).

HashMap properties = new HashMap();
properties.put("zipcode", "33000");
properties.put("establishment", "restaurant");
APM.sharedInstance(this).triggerAction("write_review", properties);

This example tag will match with the action « Write a review of a restaurant in Bordeaux ».

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.

Send multiple actions

If you need to send multiple actions at once, you must use another method:

String[] tags = new String[3];
tags[0] = "tag1";
tags[1] = "tag2";
tags[2] = "tag3";
APM.sharedInstance(this).triggerActions(tags);

3. User properties

Just like for 2. Send an action with properties, if your tagging plan requires the use of filters, you may need to send us userProperties so that we can offer filtered actions to the user.

Use the class APMUserPropertiesUtils to manage user properties.

userProperty.key : Property keys must strings. (e.g. « zipcode », « membership_level »). userProperty.value :Property values must strings. (e.g. « 33000 », « premium »).

➕Adding user properties

public void addUserProperty(String value, String key)
public void addUserProperties(HashMap userProperties)

Be careful of the order of the arguments for addUserProperty(value first) !

Example:

// Single userProperty
APMUserPropertiesUtils.getInstance().addUserProperty("premium", "membership_level");
// Multiple userProperties
HashMap userProperties = new HashMap();
userProperties.put("zipcode", "33000");
userProperties.put("membership_level", "premium");
APMUserPropertiesUtils.getInstance().addUserProperties(userProperties);

Adding a userProperty with a key that already exists will update it.

➖Removing user properties

If a userProperty is no longer valid, you can remove it (example: user does not wish to be geolocated anymore),

public void removeUserProperty(String key);
public void removeUserProperties(); // removes all user properties

Example:

// Single userProperty
APMUserPropertiesUtils.getInstance().removeUserProperty("zipcode");
// All userProperties
APMUserPropertiesUtils.getInstance().removeUserProperties();

🔄Refreshing after a change

If you have changed a userProperty that may have an impact on the actions that we can propose to the user, you will want to refresh the SDK (i.e. tell it to communicate with our API to get updated info).

You can do this by calling:

APMServicesPublic.sharedInstance().refreshSDK(true);

4. Action's deeplink

We showcase one action above others (Challenge of the day). Each action can be configured in our BackOffice with a deeplink so that the user can go to the screen where they can perform the action.

Clicking on a suggested action's deeplink

To listen to the click on the "Let's go !" 👉 button and get the deeplink URI, you need to use APMDeepLinkActionUtils and APMDeepLinkActionUtilsListener.

Example with AbstractActivity lifecycle:

public class AbstractActivity extends FragmentActivity implements APMDeeplinkListener {
​
    @Override
    protected void onResume() {
        super.onResume();
        // Start listening
        APMDeeplinkUtils.getInstance().addListener(this);
    }
​
    @Override
    protected void onPause() {
        super.onPause();
        // Stop listening
        APMDeeplinkUtils.getInstance().removeListener(this);
    }
​
    @Override
    public void apmDeeplinkOnboardingButtonOkClicked() {
        //Not used for action's deeplink
    }
​
    @Override
    public void apmDeeplinkOnboardingButtonLaterClicked() {
        //Not used for action's deeplink
    }
​
    @Override
    public void apmDeeplinkOnboardingButtonNeverClicked() {
        //Not used for action's deeplink
    }
    
    @Override
    public void apmDeeplinkActionButtonGoClicked(String url) {
        // The user clicked the "Let's go" button.
        // The big badge will automatically close
        // TODO: Use the deeplink to navigate the user to the indicated screen.
    }
    
    @Override
    public void apmDeeplinkClicked(String url) {
        //Not used for action's deeplink
    }
}

III. Advanced functions

1. Show/Hide badge 👻

You can hide the badge if you have a screen where you don't want the user to be distracted (e.g. checkout).

You can hide the badge with the method :

APM.sharedInstance(this).setBadgeEnabled(false);

And show the badge :

APM.sharedInstance(this).setBadgeEnabled(true);

Make sure to show the badge again once you leave the screen or the user may never see it again !

Day... Night...

While the badge is hidden, the SDK continues to work. If there are triggerActions, the notifications will happen once the badge is shown.

2. Activate debug logs🐞

Logs are quire useful, right ? Here's how to unleash the (controlled) fury of debug logs:

APM.sharedInstance(this).setDebugMode(true); //To show trace log app's miles

Android logs from Android Studio (logcat)

3. Listen for changes to a user

You can be notified f the user change with the class APMServicesUserListener. Set a listener with :

APMServicesPublic.sharedInstance().setServicesUserListener(this);

3 callbacks available :

• apmServicesUserChanged(APMUser user) : called when one of the user's attribute change

• apmServicesUserBalanceChanged(APMUser user) : called when the userBalance change

• apmServicesUserUnsubscribed() : called when the user unsubscribes

4. RGPD

You can disabled some features for RGPD compliances

//Disabled localization of user for SDK app's miles
APMGeolocUtils.getInstance().setGeolocEnabled(false);

5. Add attributes/customDimensions/userProperties in your analytics

You can retrieve information from SDK to powered your analytics

• "apm_user_connected" : "yes", "no"

• "apm_user_animated" : "not_set", "animated", "anonymous", "unsubscribe"

private void updateUserPropertiesAPM() {
    APMUser user = APMServicesPublic.sharedInstance().getUser();
    APMDevice device = APMServicesPublic.sharedInstance().getDevice();

    String apmUserConnected = (user != null && user.isConnected()) ? "yes" : "no";

    String apmUserAnimated = "not_set";
    if(device != null && device.getDeviceStatus() != null) {
        if(device.getDeviceStatus() == APMServicesConfig.APM_DEVICE_STATUS_OK)
            apmUserAnimated = "animated";
        else if(device.getDeviceStatus() == APMServicesConfig.APM_DEVICE_STATUS_ANONYMOUS)
            apmUserAnimated = "anonymous";
        else if(device.getDeviceStatus() == APMServicesConfig.APM_DEVICE_STATUS_OPTIN_OFF)
            apmUserAnimated = "unsubscribe";
    }

    //Batch example
//  BatchUserDataEditor editor = Batch.User.editor();
//  editor.setAttribute("apm_user_connected", (String) apmUserConnected);
//  editor.setAttribute("apm_user_animated", (String) apmUserAnimated);
//  editor.save();

    //Google Analytics example
//  tracker.send(new HitBuilders.ScreenViewBuilder().setCustomDimension(INDEX_APM_USER_CONNECTED, apmUserConnected) //INDEX_APM_USER_CONNECTED index for custom dimension : apm_user_connected
//  tracker.send(new HitBuilders.ScreenViewBuilder().setCustomDimension(INDEX_APM_USER_ANIMATED, apmUserAnimated) //INDEX_APM_USER_ANIMATED index for custom dimension : apm_user_animated

    //Firebase example
//  mFirebaseAnalytics.setUserProperty("apm_user_connected", apmUserConnected);
//  mFirebaseAnalytics.setUserProperty("apm_user_animated", apmUserAnimated);
}

Call the method updateUserPropertiesAPM() :

• after the init of SDK APM (YourAppApplication.java, in the method onCreate())

• when the user changed (use the listener APMServicesUserListener)

6. Enabled/Disabled statistics for device/user

You can activate/deactivate statistics analytics with the following method :

APMStatUtils statUtils = APMStatUtils.sharedInstance();
statUtils.setEnabledOptinStat(true, new APMUserOptinsListener() {
    @Override
    public void userOptinsSuccess(APMOptins optins) {
        if(optins.getStatistics().isEnabled()) {
            //Statistics is now activated for this device/user
        }
    }

    @Override
    public void failure(APMException e) {
        //An error occured
    }
});

If we are connected to an user account, this setting is set to user and device. If we are not connected, this setting is set to device only.

By default, statistics analytics are disabled.