In-App Messaging

In-App Messaging (IAM) module allows app developers to easily configure and display notifications within their app.

In-App Messaging Sample

This page covers:

Requirements

Supported Android Versions

This SDK supports Android API level 23 (Marshmallow) and above.

In-App Messaging Subscription Key

You must have a subscription key for your application from IAM Dashboard.

SDK Integration

#1 Include Maven Central repo in your project, this should be added in your project root build.gradle file.

allprojects {
    repositories {
        mavenCentral()
    }
}

#2 Add InAppMessaging SDK in your project dependencies.

Note: InAppMessaging SDK only uses AndroidX libraries. Host apps should migrate to AndroidX to avoid duplicate dependencies.

dependencies {
    implementation 'io.github.rakutentech.inappmessaging:inappmessaging:${latest_version}'
}

Please refer to Changelog section for the latest version.

#3 Target and compile SDK version to 31 or above.

Note: It is required to target and compile to SDK version 31 or above.

android {
    compileSdkVersion 31

    defaultConfig {
    // Defines the minimum API level required to run the app.
    minSdkVersion 23
    // Specifies the API level used to test the app.
    targetSdkVersion 31
    }
}

#4 Adding subscription ID and config URL to your app’s AndroidManifest.xml file.

<meta-data
    android:name="com.rakuten.tech.mobile.inappmessaging.subscriptionkey"
    android:value="change-to-your-subsrcription-key"/>

<meta-data
    android:name="com.rakuten.tech.mobile.inappmessaging.configurl"
    android:value="change-to-config-url"/>

If you want to enable debug logging in In-App Messaging SDK (tags begins with “IAM_”), add the following meta-data in AndroidManifest.xml file.

<meta-data
    android:name="com.rakuten.tech.mobile.inappmessaging.debugging"
    android:value="true"/>
Field Datatype Manifest Key Optional Default
Subscription Key String com.rakuten.tech.mobile.inappmessaging.subscriptionkey ❌ 🚫
Config URL String com.rakuten.tech.mobile.inappmessaging.configurl ❌ 🚫
Debugging boolean com.rakuten.tech.mobile.inappmessaging.debugging ✅ false

Enable and disable the SDK remotely

We recommend, as good engineering practice, that you integrate with a remote config service so that you can fetch a feature flag, e.g. Enable_IAM_SDK, and use its value to dynamically enable/disable the SDK without making an app release. There are many remote config services on the market, both free and paid.

#5 Creating UserInfoProvider.

Create a new class in your project that implements the following class:

com.rakuten.tech.mobile.inappmessaging.runtime.UserInfoProvider

This class serves the purpose of providing basic user information such as user ID, Access Token, and ID Tracking Identifier at runtime. These user information are used by the SDK for campaigns targeting specific users.

class AppUserInfoProvider : UserInfoProvider {

    // This method is optional for Kotlin class
    // If Access Token will not be used, no need to override this method (i.e. default value is "")
    override fun provideAccessToken(): String? {
        return accessToken
    }

    // This method is optional for Kotlin class
    // If User ID will not be used, no need to override this method (i.e. default value is "")
    override fun provideUserId(): String? {
        return userId
    }

    // This method is optional for Kotlin class
    // If ID tracking identifier will not be used, no need to override this method (i.e. default value is "")
    override fun provideIdTrackingIdentifier(): String? {
        return idTrackingIdentifier
    }
}

To help IAM identify users, please keep user information in the preference object up to date. After logout is complete, please ensure that all UserInfoProvider methods in the preference object return null or empty string.

Notes for Rakuten Developers:

#6 Initializing In-App Messaging SDK.

Host app should initialize the SDK, then register the provider containing the user information.

In your Application class’ onCreate() method, add:

// API: init(context: Context, errorCallback: ((ex: Exception) -> Unit)? = null): Boolean
// `errorCallback` lambda function is optional,
// and can be used for analytics and logging of encountered initialization issues.
val iamFlag = InAppMessaging.init(this) {
    Log.e(TAG, it.localizedMessage, it.cause)
}

// use flag to enable/disable IAM feature in your app.
if (iamFlag) {
    InAppMessaging.instance().registerPreference(provider)
}

The preference object can be set once per app session. IAM SDK will read object’s properties on demand.

Preferences are not persisted so this function needs to be called on every launch.

Notes:

#7 Registering and unregistering activities.

Only register activities that are allowed to display In-App messages. Your activities will be kept in a WeakReference object, so it will not cause any memory leaks. Don’t forget to unregister your activities in onPause() method.

Please see Context feature section to have more control on displaying campaigns.

override fun onResume() {
    super.onResume()
    InAppMessaging.instance().registerMessageDisplayActivity(this)
}

override fun onPause() {
    super.onPause()
    InAppMessaging.instance().unregisterMessageDisplayActivity()
}

#8 Logging events

Host app can log events to InAppMessaging anywhere in your app.

These events will trigger messages with the same event based trigger. Upon receiving logged event, InAppMessaging SDK will start matching it with current campaigns immediately. After a campaign message’s trigger events are matched by the logged events, this message will be displayed in the current registered activity. If no activity is registered, it will be displayed in the next registered activity.

Pre-defined event classes:

AppStartEvent

Host app should log this event on app launch from terminated state. Recommended to log this event in host app’s main activity’s Activity#onStart().

App Start Event is persistent, meaning, once it’s logged it will always satisfy corresponding trigger in a campaign. All subsequent logs of this event are ignored. Campaigns that require only AppStartEvent are shown once per app session.

class MainActivity : AppCompatActivity() {

    override fun onStart() {
        super.onStart()
        InAppMessaging.instance().logEvent(AppStartEvent())
    }
}

LoginSuccessfulEvent

Host app should log this every time the user logs in successfully.

InAppMessaging.instance().logEvent(LoginSuccessfulEvent())

PurchaseSuccessfulEvent

Host app should log this event after every successful purchase.

InAppMessaging.instance().logEvent(PurchaseSuccessfulEvent())

Custom event class:

CustomEvent

Host app should log this after app-defined states are reached or conditions are met.

Custom events can have attributes with names and values. Attributes can be integer, double, String, boolean, or java.util.Date type.

InAppMessaging.instance().logEvent(CustomEvent("search").addAttribute("keyword", "book").addAttribute("number_of_keyword", 1))

Please note: Logging events may trigger InAppMessaging SDK to update current session data if there were changes in the app’s user information (see UserInfoProvider section for details).

SDK Logic

Client-side opt-out handling

If user (with valid identifiers in UserInfoProvider class) opts out from a campaign, that information is saved in user cache locally on the device and the campaign won’t be shown again for that user on the same device. The opt-out status is not shared between devices. The same applies for anonymous user.

Client-side max impressions handling

Campaign impressions (displays) are counted locally for each user. Meaning that a campaign with maxImpression value of 3 will be displayed to each user (different identifiers in UserInfoProvider class) max 3 times. Campaign’s max impression number can be modified in the dashboard/backend. Then the SDK, after next ping call, will compare new value with old max impression number and add the difference to the current impression counter. The max impression data is not shared between devices. The same applies for anonymous user.

Advanced Features

#1 Campaign’s context

Contexts are used to add more control on when campaigns are displayed. A context can be defined as the text inside “[]” within an IAM portal “Campaign Name” e.g. the campaign name is “[ctx1] title” so the context is “ctx1”. Multiple contexts are supported. In order to handle defined contexts in the code an optional callback is called before a message is displayed:

InAppMessaging.instance().onVerifyContext = { contexts: List<String>, campaignTitle: String -> Boolean
    if /* check your condition e.g. are you on the correct screen to display this message? */ {
        true // campaign message will be displayed
    } else {
        false // campaign message won't be displayed
    }
}

#2 Close campaign API

There may be cases where apps need to manually close the campaigns without user interaction.

An example is when a different user logs-in and the currently displayed campaign does not target the new user.

It is possible that the new user did not close the campaign (tapping the ‘X’ button) when logging in. The app can force-close the campaign by calling the closeMessage() API.

InAppMessaging.instance().closeMessage()

An optional parameter, clearQueuedCampaigns, can be set to true (false by default) which will additionally remove all campaigns that were queued to be displayed.

InAppMessaging.instance().closeMessage(true)

Note: Calling this API will not increment the campaign’s impression (i.e not counted as displayed).

Troubleshooting

Proguard ParseException

Caused by: java.io.IOException: proguard.ParseException: Unknown option '-if' in line 84 of file
This error will be thrown during compilation if `minifyEnabled = true`, and your Proguard version is below 6.0.
(click to expand) Recommendation: Update your project's Android Gradle Plugin to the latest version, it includes the latest version of Proguard.

Less optimal solution: Force Gradle to use the latest version of Proguard(https://sourceforge.net/p/proguard/discussion/182455/thread/89a4d63d/):

buildscript {
    ...
    configurations.all {
      resolutionStrategy {
        force 'net.sf.proguard:proguard-gradle:6.0.3'
        force 'net.sf.proguard:proguard-base:6.0.3'
      }
    }
}

Duplicate class ManifestConfig

Build Error: java.lang.RuntimeException: Duplicate class com.rakuten.tech.mobile.manifestconfig.annotations.ManifestConfig

(click to expand)

This build error could occur if you are using older versions of other libraries from com.rakuten.tech.mobile. Some of the dependencies in this SDK have changed to a new Group ID of io.github.rakutentech (due to the JCenter shutdown). This means that if you have another library in your project which depends on the older dependencies using the Gropu ID com.rakuten.tech.mobile, then you will have duplicate classes.

To avoid this, please add the following to your build.gradle in order to exclude the old com.rakuten.tech.mobile dependencies from your project.

configurations.all {
    exclude group: 'com.rakuten.tech.mobile', module: 'manifest-config-processor'
    exclude group: 'com.rakuten.tech.mobile', module: 'manifest-config-annotations'
}

Other Issues

Rakuten developers experiencing any other problems should refer to the Troubleshooting Guide on the internal developer documentation portal.

Frequently Asked Questions

Q: How do I send message for in staging or testing environment?

When creating campaigns, you can set the versions which the campaign will be applied to your app. You can set the versions to staging versions (ex. 0.0.1, 1.0.0-staging, 0.x.x, etc.)

Q: How many times In-App Message should be sent to device? Does it depends on Max Lifetime Impressions?

The max impression is handled by SDK and is bound to user per device.

  1. Scenario- Max impression is set to 2. User does not login with any ID. So It will be shown 2 times.
  2. Scenario- Max impression is set to 2. User login with any ID for 2 devices. It will show 2 times for each device.
  3. The campaign start time can be shown

Please refer to max impression handling for more details.

Q: Is the campaign displayed if ALL or ANY of triggers are satisfied?

All the events “launch the app event, login event, purchase successful event, custom event” work as AND. It will send to the device only all defined event are triggered.

Documents targeting Engineers:

Documents targeting Product Managers:

Changelog

6.0.0 (2021-12-03)

5.0.0 (2021-09-10)

4.0.0 (2021-08-04)

3.0.0 (2021-03-24)

2.3.0 (2021-02-24)

2.2.0 (2020-11-10)

2.1.0 (2020-09-18)

2.0.0 (2020-06-11)

1.4.0

1.3.0

1.2.0