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 {
        jcenter()
    }
}

#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 'com.rakuten.tech.mobile.inappmessaging:inappmessaging:${latest_version}'
}

Please refer to Changelog section for the latest version.

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

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

android {
    compileSdkVersion 28

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

#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
    }
}

Note: only provide RAE token if the user is logged in.

#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’s 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
    }
}

Troubleshooting

proguard.ParseException (click to expand)

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.

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'
      }
    }
}

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

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