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 21 (Lollipop) and above.

In-App Messaging Subscription Key

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

SDK Integration

#1 Include JCenter 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 30 or above.

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

android {
    compileSdkVersion 30

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

#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

#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, Rakuten ID, and RAE Token at runtime. These user information are used by the SDK for campaigns targeting specific users.

class AppUserInfoProvider : UserInfoProvider {

    override fun provideRaeToken(): String? {
        return raeToken
    }

    override fun provideUserId(): String? {
        return userId
    }
    override fun provideRakutenId(): String? {
        return rakutenId
    }
}

Notes for Rakuten Developers:

#6 Initializing In-App Messaging SDK.

In-App Messaging is automatically initialized at startup and handled on a background thread. Host app just needs to register the provider containing the user information.

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

InAppMessaging.instance().registerPreference(YourUserInfoProvider())

Note: There could be exceptions thrown during initialization, if Subscription Key or other critical information was not found.

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

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 test device? Does it depends on Max Lifetime Impressions?

The max impression is bind to per device ID.

  1. Scenario- Max impression set to 2. User does not login with Rakuten ID or Easy ID. So It will be shown in single device for 2 times.
  2. Scenario- Max impression is set to 2. User login with Rakuten ID or easy ID for 2 devices. It will show 2 times per devices.
  3. The campaign start time can be shown

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

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