in app - optimove-tech/Optimove-SDK-Android GitHub Wiki

Enabling In-App Messages

To integrate In-App messaging you only need to configure the SDK to enable the feature during initialization.

OptimoveConfig config = new OptimoveConfig.Builder(
    "<YOUR_OPTIMOVE_CREDENTIALS>","<YOUR_OPTIMOVE_MOBILE_CREDENTIALS>"
    ).enableInAppMessaging(OptimoveConfig.InAppConsentStrategy.AUTO_ENROLL)
    .build()

Optimove.initialize(this, config);

This configuration will automatically enroll all your app users to be reachable by In-App messages, the SDK will automatically present and track opens.

Managing In-App User Consent

If you would like your users to opt-in to receive In-App messages you can configure the SDK during initialization to make opt-in explicit by setting the strategy, then calling the SDK helper to manage their consent.

// Set the strategy to require explicit user consent
OptimoveConfig config = new OptimoveConfig.Builder(
    "<YOUR_OPTIMOVE_CREDENTIALS>","<YOUR_OPTIMOVE_MOBILE_CREDENTIALS>"
    ).enableInAppMessaging(OptimoveConfig.InAppConsentStrategy.EXPLICIT_BY_USER)
    .build()

Optimove.initialize(this, config);

// Call this method to update consent based on user preferences / settings screen etc.
OptimoveInApp.getInstance().updateConsentForUser(true);

Deep-linking for In-App

In-App messages allow you to hand-off to native application screens via deep-linking action buttons. When tapped, these buttons pass control to the defined deep-link handler, including their defined data payload (configured in the In-App message composer for the action button).

If you want to handle deep-links with custom data payloads as part of an In-App message you can create a class that implements the InAppDeepLinkHandlerInterface and add it to your configuration options during SDK initialization:

OptimoveInApp.getInstance().setDeepLinkHandler((context, buttonPress) -> {
    JSONObject deepLink = buttonPress.getDeepLinkData();
    JSONObject messageData = buttonPress.getMessageData();

    // TODO: Inspect the deep link & message data to perform relevant action
});

Using the In-App Inbox

In-app messages can optionally be persisted in a user-level inbox for later retrieval. This allows you to build features such as loyalty rewards or expiring coupons into your app. Regardless of whether they are stored in the inbox, the maximum amount of in-apps stored on a device is 50 (the oldest messages exceeding this limit will be evicted).

Retrieve messages

To retrieve a list of messages from the user's inbox and present the first in the list, see the following example:

List<InAppInboxItem> items = OptimoveInApp.getInstance().getInboxItems();
if (items.size() != 0) {
    OptimoveInApp.InboxMessagePresentationResult result = OptimoveInApp.getInstance().presentInboxMessage(items.get(0));
}

Note that if in-app message display is paused then inbox items will not be presented and will instead return the status PAUSED to allow your app to handle the condition.

Mark as read

To mark a single or all inbox messages as read:

//single
List<InAppInboxItem> items = OptimoveInApp.getInstance().getInboxItems(context);

if (items.size() != 0) {
    OptimoveInApp.getInstance().markAsRead(context, items.get(0));
}

//all
OptimoveInApp.getInstance().markAllInboxItemsAsRead(context);

Delete message

You can also delete an in-app message from inbox:

List<InAppInboxItem> items = OptimoveInApp.getInstance().getInboxItems(context);
if (items.size() != 0) {
    OptimoveInApp.getInstance().deleteMessageFromInbox(context, items.get(0));
}

Inbox updated handler

In order to be notified when inbox changes you may set up a handler. The handler fires on the UI thread when one of the following happens to an in-app with an inbox configuration:

  • message fetched from server
  • message opened
  • message marked as read
  • message deleted
  • message evicted (expires or limit of stored messages exceeded)

You can use it as follows:

OptimoveInApp.getInstance().setOnInboxUpdated(() -> {
    List<InAppInboxItem> items = OptimoveInApp.getInstance().getInboxItems(context);

    //refresh your inbox
});

Note, you can do OptimoveInApp.getInstance().setOnInboxUpdated(null) when you stop being interested in inbox updates.

Get inbox summary

You can retrieve an inbox summary as follows:

OptimoveInApp.getInstance().getInboxSummaryAsync(context, (InAppInboxSummaryInfo summary) -> {
    if (summary != null){
        summary.getTotalCount();
        summary.getUnreadCount();
    }
});

The method runs asynchronously and calls back on the UI thread.

Get inbox item's image URL

Each inbox item may have an image associated with it. getImageUrl returns a URL to the image of specified width or null if there is no image.

List<InAppInboxItem> items = OptimoveInApp.getInstance().getInboxItems(context);

if (items.size() != 0) 
{
    // Default width is 300px
    URL u = items.get(0).getImageUrl();

    // Get URL to a 200px wide image
    URL u = items.get(0).getImageUrl(200);
}

Controlling In-app Message Display

SDK version 7.2.0+

It is possible to temporarily pause & resume in-app message display. This can be useful to prevent in-apps showing on particular screens in your app or interrupting full-screen experiences.

There are two in-app display modes defined:

  • AUTOMATIC (the default): in-app messages are shown as soon as eligible
  • PAUSED: in-app messages may be queued for display, but not shown to the user

If display is paused, and then set to automatic, display is considered 'resumed' and any messages queued whilst the display was paused will be shown to the user as normal.

Setting the display mode

You can use the following APIs to manipulate the in-app display mode:

OptimoveInApp.getInstance().setDisplayMode(OptimoveConfig.InAppDisplayMode.PAUSED);
OptimoveInApp.getInstance().setDisplayMode(OptimoveConfig.InAppDisplayMode.AUTOMATIC);
OptimoveConfig.InAppDisplayMode mode = OptimoveInApp.getInstance().getDisplayMode();

Changing display mode whilst an in-app message is showing will take effect once the current message is closed.

Attempting to present an inbox item whilst display is paused will return a status enum indicating that display is paused, and the item is not presented.

Setting a default display mode

If you don't want in-app messages to show whilst your app is loading, you can use the following configuration option to pause in-app display by default:

OptimoveConfig config = new OptimoveConfig.Builder(
    "<YOUR_OPTIMOVE_CREDENTIALS>","<YOUR_OPTIMOVE_MOBILE_CREDENTIALS>"
    ).enableInAppMessaging(OptimoveConfig.InAppConsentStrategy.AUTO_ENROLL, OptimoveConfig.InAppDisplayMode.PAUSED)
    .build()

Then, when you are ready to resume display, you can set the mode to automatic:

OptimoveInApp.getInstance().setDisplayMode(OptimoveConfig.InAppDisplayMode.AUTOMATIC);