Set up In-App Messages

📘
Wait. Are you ready for this part?
In this article, we'll show you how to send messages from our platform to your app's users when they are using your app. However, this cannot work until you have the SDK in your project and you can use it in your app. If not, then we suggest that you do those things first and then come back here to send in-app messages.
It's absolutely not complicated. We promise. And, like earlier, we'll wait. No pressure. ☺️

Enable In-App Messages

Enable the feature during the SDK initialization using the following configuration methods during the SDK initialization:

configuration.setInAppEnabled(true)
// Consent to show HTML in-app messages with JavaScript in them.
configuration.setJavaScriptForInAppWebViewEnabled(true)

configuration.setInAppEnabled(true);
// Consent to show HTML in-app messages with JavaScript in them.
configuration.setJavaScriptForInAppWebViewEnabled(true);

Display In-App Messages

To show in-app messages, you need to register the app's screens with the Blueshift SDK. There are several ways to accomplish this:

Register individual screens

To register an individual screen for showing in-app messages, you should call the following method from your Activity's onStart() method:

Blueshift.getInstance(context).registerForInAppMessages(activity)

Blueshift.getInstance(context).registerForInAppMessages(activity);

In this case, the name of the screen will be the local class name of the activity object. For example, if you have an activity named MainActivity under the package com.example.app, it will be registered as "com.example.app.MainActivity" for in-app messages.

Register individual screens with a custom screen name

In some cases, you may want to assign a custom name to the current screen instead of using the activity's local class name. This is particularly useful when using Fragments as screens on top of an Activity. To do this, call the following method:

Blueshift.getInstance(context).registerForInAppMessages(activity, "screen_name")

Blueshift.getInstance(context).registerForInAppMessages(activity, "screen_name");

Replace "screen_name" with the desired name for the current screen. This allows you to provide a more descriptive name for better targeting of in-app messages that are designed for specific screens.

Register all screens

If you prefer to register all your activities without writing code in individual files, you can add an ActivityLifecycleCallback in your app's application class. This callback provides methods that are triggered when activities are created, started, stopped, etc. By implementing it, you can automatically register and unregister activities for in-app messages.

Here's an example of implementing ActivityLifecycleCallbacks in your application class:

class YourApplication : Application(), Application.ActivityLifecycleCallbacks {

    // Other methods...
  
    override fun onActivityStarted(activity: Activity) {
        Blueshift.getInstance(activity).registerForInAppMessages(activity)
    }
  
    // Other methods...
  
    override fun onActivityStopped(activity: Activity) {
        Blueshift.getInstance(activity).unregisterForInAppMessages(activity)
    }
  
    // Other methods...
}

public class YourApplication extends Application implements Application.ActivityLifecycleCallbacks {
  
    // Other methods...
  
    @Override
    public void onActivityStarted(@NonNull Activity activity) {
        Blueshift.getInstance(activity).registerForInAppMessages(activity);
    }
  
    // Other methods...
  
    @Override
    public void onActivityStopped(@NonNull Activity activity) {
        Blueshift.getInstance(activity).unregisterForInAppMessages(activity);
    }
  
    // Other methods...
}

By adding this callback, all activities in your app will be automatically registered for in-app messages when they start and unregistered when they stop.

Unregister screens

When navigating away from a screen that is registered for in-app notifications, it is important to unregister the screen for cleanup. This ensures that resources are properly managed and prevents any unwanted display of in-app messages.

To unregister a screen, use the following method:

Blueshift.getInstance(context).unregisterForInAppMessages(activity)

Blueshift.getInstance(context).unregisterForInAppMessages(activity);

Make sure to call this method when the screen is no longer active or visible to the user.

In-app message deep links

When clicking on deep links in the in-app messages, Blueshift SDK will trigger a VIEW intent with the deep link URL as its data. Handling this is the same as handling deep links in Android.

Setup the deep link receiver Activity in the AndroidManifest.xml

<activity
    android:name=".DeeplinkActivity"
    android:exported="true">
    <intent-filter
        android:autoVerify="true"
        tools:targetApi="m">
        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data android:scheme="https" />
        <data android:host="example.com" />
    </intent-filter>
</activity>

Setup the deep link handling in the receiver Activity

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_splash_screen);

    Uri uri = getIntent().getData();
    if (uri != null) {
      handleDeepLink(uri);
    }
}

Advanced Configuration

In this section, we cover advanced topics related to in-app messages, providing you with more control and customization options.

In-App Background Fetch

Starting from version 3.1.1, the Blueshift SDK automatically fetches in-app messages from the server when it receives a silent push message after a test send or campaign execution. If you wish to modify this behavior, you can use the following configuration method during SDK initialization:

configuration.setInAppBackgroundFetchEnabled(true)

configuration.setInAppBackgroundFetchEnabled(true);

Disabling this feature prevents the SDK from automatically fetching in-app messages from the server. If you still want to get the in-app messages, you can do so manually using the method mentioned below.

Manual Trigger for In-App Messages

By default, the SDK fetches in-app messages from the server and displays them to the user when they open the registered screen. However, if you require full control over this process, you can enable manual mode during SDK initialization using the following configuration method:

configuration.setInAppManualTriggerEnabled(true)

configuration.setInAppManualTriggerEnabled(true);

When manual mode is enabled, the SDK behaves as follows:

It will not fetch in-app messages on app start.
It will not automatically display in-app messages under any circumstances.
It will only fetch and store in-app messages when a silent push is received.
It will only display in-app messages when the Blueshift.getInstance(this).displayInAppMessages() method is invoked.

Manually Fetching In-App Messages

When the manual trigger is enabled and you want to fetch in-app messages from the server, use the following method:

Blueshift.getInstance(this).fetchInAppMessages(object : InAppApiCallback {
    override fun onSuccess() {
        Log.d(TAG, "In-App API fetch success!")
    }

    override fun onFailure(errorCode: Int, errorMessage: String) {
        Log.d(TAG, "In-App API fetch failed!")
    }
})

Blueshift.getInstance(this).fetchInAppMessages(new InAppApiCallback() {
    @Override
    public void onSuccess() {
        Log.d(TAG, "In-App API fetch success!");
    }

    @Override
    public void onFailure(int errorCode, String errorMessage) {
        Log.d(TAG, "In-App API fetch failed!");
    }
});

This method downloads all the in-app messages and stores them in the local database. Note that calling this method will not automatically display the in-app messages to the user when the manual trigger is enabled.

Manually Displaying In-App Messages

When the manual trigger is enabled and you want to show the in-app messages to the user, use the following method:

Blueshift.getInstance(this).displayInAppMessages()

Blueshift.getInstance(this).displayInAppMessages();

This method will only show an in-app message if:

There is at least one eligible in-app message in the local database.
The current screen is registered to show in-app messages.

In-App Interval

By default, the time interval between two in-app displays (from when a message is dismissed until the next message appears) while staying on the same screen is 1 minute. However, you can change this value using the following configuration method during the SDK initialization:

configuration.setInAppInterval(seconds)

configuration.setInAppInterval(seconds);

In-App Event Listeners

Starting from SDK version 3.1.9, you can listen to actions such as delivered, opened, and clicked for in-app messages by registering listeners. Here's an example:

Blueshift.setBlueshiftInAppListener(object : BlueshiftInAppListener {
    override fun onInAppDelivered(inappMap: Map<String, Any>) {
        Log.d(TAG, "onInAppDelivered:")
    }

    override fun onInAppOpened(inappMap: Map<String, Any>) {
        Log.d(TAG, "onInAppOpened:")
    }

    override fun onInAppClicked(inappMap: Map<String, Any>) {
        Log.d(TAG, "onInAppClicked:")
    }
})

Blueshift.setBlueshiftInAppListener(new BlueshiftInAppListener() {
    @Override
    public void onInAppDelivered(Map<String, Object> inappMap) {
        Log.d(TAG, "onInAppDelivered:");
    }

    @Override
    public void onInAppOpened(Map<String, Object> inappMap) {
        Log.d(TAG, "onInAppOpened:");
    }

    @Override
    public void onInAppClicked(Map<String, Object> inappMap) {
        Log.d(TAG, "onInAppClicked:");
    }
});

By implementing these listeners, you can capture events related to the delivery, opening, and clicking of in-app messages, allowing for further customization and analytics tracking.

Frequently Asked Questions

Here are some frequently asked questions regarding the control and behavior of in-app messages:

Q: I want to control when the app displays the in-app messages. How do I do that?
A: To have control over when your app displays in-app messages, you can follow these steps:

Enable manual mode during the SDK initialization to indicate that the SDK should not display in-app messages automatically.
Use the displayInAppMessages() method to show the in-app messages whenever you want them to be displayed. This allows you to manually trigger the in-app messages. For more information, please refer to the section on "Trigger in-app messages manually."

Q: What happens when I turn the manual mode ON?
A: Enabling manual mode provides you with full control over the display of in-app messages. Here's what happens when manual mode is enabled:

The SDK will not automatically fetch the content for in-app messages when a customer launches the app.
The SDK will fetch the content for in-app messages only when a silent push is received.
The SDK will not display an in-app message automatically after fetching new content through a silent push.
You can use the displayInAppMessages() method to manually display the in-app messages when desired. For more details, refer to the section on "Trigger in-app messages manually."

Q: What is background fetch or silent push for in-app messages?
A: Background fetch or silent push is a process where the Blueshift server sends a push notification to the device to inform the SDK about the availability of a new in-app message. This push notification triggers the SDK to call the in-app API and fetch the latest content for the in-app message. It allows the app to update the in-app messages silently in the background.

Q: What happens if the user revokes the notification permission? Will I still receive silent push messages for fetching in-app messages?
A: When a user revokes the push notification permission using the app settings, the app is no longer able to add notifications to the notification tray. However, this does not prevent the app from receiving push messages, including silent push messages. Therefore, even if the notification permission is revoked, your app can still receive silent push messages to fetch the latest in-app messages from Blueshift.

📘Wait. Are you ready for this part?

Enable In-App Messages

Display In-App Messages

Register individual screens

Register individual screens with a custom screen name

Register all screens

Unregister screens

In-app message deep links

Advanced Configuration

In-App Background Fetch

Manual Trigger for In-App Messages

Manually Fetching In-App Messages

Manually Displaying In-App Messages

In-App Interval

In-App Event Listeners

Frequently Asked Questions

📘
Wait. Are you ready for this part?