• Dashboard
  • API
  • Guides
  • FAQ
  • Documentation > Android

    In-App Messaging

    Batch 1.10 introduces In-App Campaigns.

    In-App Campaigns allow you to trigger messages when users open your app or perform a specific action. This is great to communicate with users who have turned off push notifications or to show contextual messages while your users are browsing your app (e.g. special offers, update reminder, etc).

    In-App formats

    Requirements

    In-App Messaging takes full advantage of mobile landings: If they are already working in your app, In-App Messaging should work out of the box.
    Your app must have:

    • Batch SDK 1.10 or higher (banners are supported from the version 1.11).
    • A minimum SDK version of 15 (Android 4.0.4)
    • The Android v4 support library (version 25 or higher)
    • The Android appcompat v7 library (version 25 or higher)

    Displaying In-App messages

    Fully automatic mode

    There is no code required to make In-App Messages work in automatic mode. Create some campaigns on your dashboard, and they will start coming up in your app.
    If they don't, please head over to the troubleshooting section.

    The automatic mode will only work properly if Batch is well integrated into ALL of your activities.

    Controlling the display using "Do Not Disturb mode"

    You can also get more control on when messages are displayed without giving up on the automatic mode, by using the "Do Not Disturb" (DnD) mode.
    It allows you to tell Batch to hold on an in-app message for you, rather than display it without using the fully manual mode.
    For example, if launching your app results in a splash screen or a fullscreen ad, you might find it undesirable to have Batch display something on top of it.

    Turning on "Do Not Disturb" mode will make Batch enqueue the latest message, rather than display it.

    Toggling DnD

    Now, when you don't want Batch to automatically display, turn on Do Not Disturb:

    Batch.Messaging.setDoNotDisturbEnabled(true)

    Once you want to start showing messages automatically, call the method with false to turn it off.

    Note: Disabling Do Not Disturb mode does NOT make Batch show the enqueued message

    Displaying pending mobile landings

    After coming back from DnD mode, you might want to show the enqueued message, as Batch will not do that automatically. Batch exposes two methods for managing the queue:

    • Batch.Messaging.hasPendingMessage() , allowing you to peek into the queue.
    • Batch.Messaging.popPendingMessage() , allowing you to fetch the pending message (if any). Since calling this makes Batch delete its reference to it to save memory, further calls might return null.

    Here is a quick example of how they can be used:

    public void splashScreenDismissed(Context context) {
        Batch.Messaging.setDoNotDisturbEnabled(false);
        BatchMessage msg = Batch.Messaging.popPendingMessage();
        if (msg != null) {
            Batch.Messaging.show(context, msg);
        }
    }

    Note: Only the latest message is queued: if an in-app message is triggered while one is still pending, it will overwrite the previous one.

    Manual mode

    Like Mobile Landings, you may want to take full control over how in-app messaging behaves. Batch allows you to disable automatic displaying, and handle that yourself. For compatibility reasons, Batch.Messaging.setAutomaticMode(false) does not control this behavior like it does on mobile landings.

    In order to handle messages yourself, you will have to set an implementation of the Batch.Messaging.LifecycleListener2 interface as a lifecycle listener.

    You'll then have the option to handle the message yourself, or let Batch continue processing it as if it was in automatic mode.
    Here is an example:

    public class SampleApplication extends Application
    {
    
        @Override
        public void onCreate()
        {
            super.onCreate();
            Batch.Messaging.setLifecycleListener(new InAppAwareListener());
        }
    }
    
    public class InAppAwareListener implements Batch.Messaging.LifecycleListener2
    {
      // ...LifecycleListener interface method implementations...
    
      public boolean onBatchInAppMessageReady(@NonNull BatchInAppMessage message)
      {
        // Sample implementation that prevents messages from being displayed if the logged in user isn't the right one
        // "getLoggedInUsername()" is an hypothetical method that returns the logged in username as a string, if logged in
        if (message.getCustomPayload().optString("username", "").equals(getLoggedInUsername()))
        {
          // Returning false tells Batch that we didn't want to handle the message.
          // Batch will then display it
          return false;
        }
        return true;
      }
    }

    Troubleshooting

    In-App messages fail to show

    This can come from multiple things:

    • Batch might not be able to display the message: make sure all of the prerequisites are satisfied by your app.
      If proguard is enabled, try disabling it temporarily.

    • The In-App campaign might not have been synchronized yet. Try to kill and restart your app: backgrounding it might not be enough.

    • If the trigger is "next session", you might just not have triggered a new session yet. Try force killing and restarting the app, or wait 5 minutes with the app in the background.
      Restarting the app might be needed twice: once to sync the campaigns, and once to trigger the "new session" event.

    • If you triggered any In-App message, you will not be able to show another without waiting at least one minute between them.
      This might change into the future.

    If that does not fix the problem, please check the logs using logcat and see if Batch outputs anything.
    If not, you can always contact our support team with information about your problem.