Documentation > Android

Mobile landings

Batch 1.7 introduces Mobile Landings.

Mobile Landings allow you to easily introduce continuity between your app, and your pushes: A user opening a push will be greeted by a rich message related to what they opened, rather than just ending up on your app's main menu.

They're included in the Premier and Enterprise plans.

Mobile landings visual example

Requirements

In order to use mobile landings, your app must have:

  • Batch SDK 1.7 or higher
  • A minimum SDK version of 15 (Android 4.0.4)
  • The Android v4 support library (version 23 or higher)
  • The Android appcompat v7 library (version 23 or higher)
  • Completed the push integration

Batch Messaging works with support v4 fragments, not standard Android ones. If using the manual mode, your displaying activity will need to be based on android.support.v4.app.FragmentActivity (AppCompatActivity is).

Displaying the message

Fully automatic mode

There's no code required to make mobile landings work in automatic mode once you satisfy the requirements: Just attach a landing to your push campaign, and Batch will display it.

You might want to go further into this documentation, setup your analytics listener or add some Custom Actions.

The automatic mode is only guaranteed to work properly if Batch is well integrated into ALL of your activities. Activities with special launchModes (such as singleTask, ...) might require a more manual integration due to platform limitations.

Automatic mode, with a custom receiver

If you're using a custom push receiver, Batch will automatically display landings when a notification is opened. However, landings will not appear when the app is in the foreground as opposed to the fully automatic mode.

For that, you'll need to implement foreground push yourself. Here's how Batch does it, which will probably work for you:

  • Track if your app is in the foreground or background. That's done by counting onPause and onResume events, using a ActivityLifecycleCallbacks implementation
  • In the push service, check this value. If the app is in the foreground and the push contains a landing, start an activity that will display the message. You can also use a LocalBroadcastManager to communicate with your foreground app.

The SDK comes com.batch.android.MessagingActivity, which is a public api: feel free to use it. MessagingActivity.startActivityForMessage() is the static method used to correctly configure this activity and show it for a given landing message.

We'll soon provide sample code to do so, feel free to contact our support in the meantime!

Once that's handled, simply make sure you call Batch.Push.displayNotification() or Batch.Push.appendBatchData() depending on how custom your receiver is, and that Batch is started in the activity opened by the notification.

Manual mode

You may want to be in control of if, when and how the landings will be loaded and displayed. Batch allows you to disable automatic displaying, and handle loading and displaying of the fragment itself.

Most integrations do not need to use this mode unless the app you're integrating into has some specificities, such as: games, non native-frameworks, activities with special launchMode, etc. The Automatic mode, with a custom receiver section might be what you're looking for, rather than doing a fully manual integration.

First, you'll need to disable the automatic mode, in your Application class:

public class SampleApplication extends Application implements Messaging.LifecycleListener
{

    @Override
    public void onCreate()
    {
        super.onCreate();
        [...]
        Batch.Messaging.setAutomaticMode(false);
    }
}

Then, you need to ask Batch to load the right fragment for the push payload (if applicable), and display it:

public class MainActivity extends FragmentActivity
{

    @Override
    protected void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);
        [...]

        final Bundle extras = getIntent().getExtras();
        if (extras != null)
        {
            try
            {
                BatchPushPayload pushPayload = BatchPushPayload.payloadFromBundle(extras);
                if (pushPayload.hasLandingMessage())
                {
                    try
                    {
                        Batch.Messaging.loadFragment(this, pushPayload.getLandingMessage())
                          .show(getSupportFragmentManager(), "batch-landing");
                    }
                    catch (BatchMessagingException e)
                    {
                        e.printStackTrace();
                    }
                }
            }
            catch (BatchPushPayload.ParsingException e)
            {
                e.printStackTrace();
            }
        }
    }

}

Note: You'll need to use the Support Fragment Manager to display the message fragment, rather than the standard one.

Controlling the display using "Do Not Disturb mode"

Batch 1.10 adds a "Do Not Disturb" (DnD) feature: It allows you to tell Batch to hold on a mobile landing 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 mobile landing, 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 landings 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 a mobile landing arrives while one is still pending, it will overwrite the previous one.

Listening to lifecycle events and button callbacks

Setting up a listener

Batch's messaging module supports setting up a listener, which can be used for analytics purposes.

It can be any object that implements the Batch.Messaging.LifecycleListener interface, such as your application instance.

public class SampleApplication extends Application implements Batch.Messaging.LifecycleListener
{

    @Override
    public void onCreate()
    {
        super.onCreate();
        [...]
        Batch.Messaging.setLifecycleListener(this);
    }

}

Analytics listener

Batch can notify your listener of lifecycle events of the in-app messages:

You shouldn't perfom any user-facing action when implementing batchMessageButtonClicked : this ID should only be used for tracking purposes. If you want to respond to a custom action, please scroll down and look for performBatchMessageAction.

The messageIdentifier and buttonIdentifier variables are the message and button tracking identifier you've configured in the dashboard. They can be nil if you didn't specify one.
For the default cancel button, buttonIdentifier will be equal to the Batch.Messaging.CLOSE_BUTTON_TRACKING_IDENTIFIER constant.

public class SampleApplication extends Application implements Batch.Messaging.LifecycleListener
{

    @Override
    public void onBatchMessageShown(@Nullable String messageIdentifier)
    {
        Log.i("App", "onBatchMessageShown " + messageIdentifier);
    }

    @Override
    public void onBatchMessageClosed(@Nullable String messageIdentifier)
    {
        Log.i("App", "onBatchMessageClosed " + messageIdentifier);
    }

}

Customizing the landing

Setting a custom typeface

If you'd like to use a custom typeface (aka font) instead of the system's, Batch allows you to override the fonts it will use:


// Set a custom typeface

Typeface normalTypeface = Typeface.createFromAsset(getAssets(), "MyFont.ttf");
Typeface boldTypeface = Typeface.createFromAsset(getAssets(), "MyFont-Bold.ttf");
Batch.Messaging.setTypefaceOverride(normalTypeface, boldTypeface);

// Clear the custom typeface, and use the system one
Batch.Messaging.setTypefaceOverride(null, null);

Make sure you provide both a normal and a bold font, even if they are the same.

This assumes you've already know how to make custom Typefaces. It usually simply involves putting fonts in your assets folder.

Troubleshooting

Landings are not displayed, even after opening the notification

First, check your logcat to see if Batch is saying anything. Then, if you're using a custom receiver, you might want to double check that you're calling required Batch methods. Activities with custom launchModes can also interfere: make sure onNewIntent is implemented correctly if you're using a special launchMode.

If you still don't get landings, don't hesitate to hit us up at support@batch.com, or by using the support button on the lower right corner of this page.

Nothing happens when I press an actionable button

Take a look at your application logs in logcat (either in your Android Studio tab, or by running "adb logcat" in a terminal): the SDK might try to warn you about an issue.

If your action isn't a deeplink but a custom action, please continue to the Custom Actions documentation.