📘

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.

If you look at the get started article, we have described the values of the configuration class that you can use to configure the SDK. You can use the following methods of the configuration class to enable in-app messages from our Android SDK.

Enable in-app messages and JavaScript

Use the following method at the time of initialization to enable in-app messages. In addition, enable the use of JavaScript in the in-app WebView so that the HTML based templates work without issues.

configuration.setInAppEnabled(true);
configuration.setJavaScriptForInAppWebViewEnabled(true);

Blueshift.getInstance(this).initialize(configuration);

Show in-app messages on your app's pages

To show in-app messages on your app's pages, use the following method to register these pages or activities with the SDK. You can show messages only on the activities that you register with Blueshift.

Use the following method to register a page.

@Override
protected void onStart() {
    super.onStart();
    Blueshift.getInstance(context).registerForInAppMessages(activity);
}

Ensure that you unregister an activity after you use it.

@Override
protected void onStop() {
    Blueshift.getInstance(context).unregisterForInAppMessages(activity);
    super.onStop();
}

In some cases, you might want to give your activity/fragments names that you can easily remember. For example, "product_details". To register your activity/fragment with this name, pass it as the second argument of the registerForInAppMessages method.

@Override
protected void onStart() {
    super.onStart();
    Blueshift.getInstance(context).registerForInAppMessages(activity, "product_details");
}

If all your pages need to support in-app messages, you can do this globally with the help of ActivityLifecycleCallbacks.

public class YourApplication extends Application implements Application.ActivityLifecycleCallbacks {
  
    @Override
    public void onActivityCreated(@NonNull Activity activity, @Nullable Bundle savedInstanceState) {
      
    }
  
    @Override
    public void onActivityStarted(@NonNull Activity activity) {
        Blueshift.getInstance(activity).registerForInAppMessages(activity);
    }
  
    @Override
    public void onActivityResumed(@NonNull Activity activity) {
      
    }
  
    @Override
    public void onActivityPaused(@NonNull Activity activity) {
      
    }
  
    @Override
    public void onActivityStopped(@NonNull Activity activity) {
        Blueshift.getInstance(activity).unregisterForInAppMessages(activity);
    }
  
    @Override
    public void onActivitySaveInstanceState(@NonNull Activity activity, @NonNull Bundle outState) {
      
    }
  
    @Override
    public void onActivityDestroyed(@NonNull Activity activity) {
      
    }
}

Fetch in-app messages in the background

Normally, the SDK fetches the content of the in-app message when a user launches your app. However, you can use the setInAppBackgroundFetchEnabled method of the SDK to fetch the content of the message silently when a user is not using your app. This feature is enabled by default since v3.1.1.

configuration.setInAppBackgroundFetchEnabled(true);

When you use this method, the SDK fetches the content, stores it locally, and triggers the in-app display. If you don't want the SDK to trigger the in-app display automatically, implement manual trigger of the in-app messages.

Trigger in-app messages manually

In addition to the SDK fetching in-app message payloads automatically from the Blueshift platform, the SDK provides methods to manually fetch content for payloads. You can use these methods to stop the SDK from fetching in-app contents and displaying messages automatically.

To enable manual in-app trigger:

configuration.setInAppManualTriggerEnabled(true);

You can implement the following methods to manually fetch content from the Blueshift platform with or without enabling the above flag. However, we recommend that you enable the above flag when the SDK is initialized to get a full control on manual in-app messaging.

To perform an in-app API call:

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!");
    }
});

To manually display content in-app:

Blueshift.getInstance(this).displayInAppMessages();

Configure time intervals

By default, the time-interval between two in-app messages (the interval when a message is dismissed and the next message appears) is one minute. You can use the following method to configure this interval when the SDK is initialized.

configuration.setInAppInterval(timeInSeconds);

If multiple in-app messages are queued for the user, the next in-app message is displayed after 1 min (or the time you specify here) from the moment the user dismisses the current in-app message.

Override actions

You can use the SDK to implement callbacks to an action a user performs on the in-app message. For example, you can implement a callback to the SDK if a user taps on the close button of the in-app message.

At the moment, our SDK supports the following actions:

• open: This action takes android_link as an argument, and it opens a page either in-app or using the browser based on the link's type.
• share: This action takes shareable_content as an argument, and provides an option to share the content in the apps that support the content.
• rate_app: This action launches Google Play Store with the app’s details page where the user can provide a rating for the app.

To use the options of the SDK to override default actions of the in-app messages and use the SDK provided actions, use the following method:

Blueshift.getInstance(this)
        .setInAppActionCallback(new InAppActionCallback() {
            @Override
            public void onAction(String actionName, JSONObject actionArgs) {
                // use the action name and arguments to implement your flow
            }
        });

Some of the actionable arguments (actionArgs) that you can use above are:

• open: { “android_link” : “http://google.com”}
• share: { “shareable_content” : “share this to get a new rangoli!” }

There are no arguments for other actions, so either expect a null or an empty JSON in that case.

In-app message event listeners

Min SDK version 3.1.9

You can set listeners to receive callbacks when an in-app message is delivered/opened/clicked. This is useful when you would like to track these events from outside the Blueshift SDKs.

The in-app payload along with additional info such as clicked element and URL will be passed in as a Map object in all 3 callbacks.

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

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

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

FAQs

I want to control when the app displays the in-app messages. How do I do that?
To control when your app displays the in-app messages, perform the following steps:

1. Enable the manual mode to let SDK know that it should not display the in-app messages automatically.
2. Call the method for displaying the in-app to show in-app message whenever you want the app to show them.
   For more information, see Trigger in-app messages manually.

What happens when I turn the manual mode ON?
When you turn on the manual mode:

• The SDK does not fetch the content for in-app messages when a customer launches the app
• The SDK fetches the content for in-app messages
• The SDK doesn't display an in-app message after it fetches new content on silent push
• The SDK displays an in-app message only when the host app calls the SDK's displayInAppMessage method. For more information, see Trigger in-app messages manually.

What is background fetch or silent push for in-app messages?
When a new in-app message is available for a customer, the Blueshift server sends a push notification to the device. The push notification tells the SDK to call the in-app API and fetch the latest content. This push notification is called a silent push for in-app messages and this entire process is called background fetch.

What happens if the user revokes the notification permission? Will I be able to get silent push messages for fetching in-app messages?
When a user revokes the push notification permission using the settings of an app, the app cannot add a notification to the notification tray. But, this does not block the app from receiving push messages. So, the app can receive silent push messages to get the latest in-app messages from Blueshift.