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

    Inbox

    Inbox is an optional feature. If you're interested, please contact us.

    Introduced in Batch 1.9, the Inbox API allows you to fetch and process notifications that this user has previously received, even if their device was offline.
    You can then do anything you want with the data, such as making a "notification center", where the user can catch up with previous notifications in a list:

    Inbox android example

    This screenshot is an example of what you can achieve with the Inbox API, but Batch does not include any UI.

    The API gives you access to the entire notification, including its raw payload. It also lets you know if the notification has already been read, and allows you to mark one or all notifications as such.

    Note: Just keep in mind that, once received/stored in the inbox your push notifications will remain for a 3 months period.

    Let's get started!

    Picking the right fetcher

    The Inbox API has two modes:

    • Installation
      This mode will fetch notifications that the current app installation, and nothing else. If the user clears the app's data, this inbox will be cleared.
      This is great for applications where your users don't have to log in.
      This may cause privacy issues if your app has an identification system.
    • User
      This mode will fetch notifications for the specified custom user ID, even if they just installed the application and already got notifications on another device logged in with the same user identifier.
      If your application has a login system, this is the mode you should use.

    Installation mode

    In this mode, you can simply get the Inbox Fetcher with a context:

    BatchInboxFetcher inboxFetcher = Batch.Inbox.getFetcher(context);
    

    Custom User ID mode

    Since notifications can have sensitive content, you cannot get a user's notifications simply with their user identifier: Batch requires you to authenticate your request.

    Getting your authentification key

    First, you will need your inbox secret key. You will find that in your dashboard, below your API Keys. It is unique for every app.

    Inbox secret dashboard screenshot

    The authentification key is generated by computing a sha256 hmac hash of the API Key and the user identifier, using the secret as the key. Then, you have to encode the hash in a hexadecimal string.

    For example, in PHP, that would be:

    hash_hmac("sha256", $APP_API_KEY . $USER_ID, $INBOX_SECRET)
    

    For the API Key "abcdef", user identifier "paul", and secret of "foobar", the expected authentication key would be 796f1ab5d119d1b2eab8201e60335b56d1befff40c0f80263d64a169a8fd2e45.

    Important note: This hash HAS to be computed on your server. If you bundle the inbox secret in your application to compute the hash, attackers will be able to extract it, and read the notifications of any of your users

    Getting the fetcher instance

    Once you've got the authentification key from the server, you only have to give Batch the right user identifier and auth key tuple to get the Inbox Fetcher:

    BatchInboxFetcher inboxFetcher = Batch.Inbox.getFetcher("paul", "796f1ab5d119d1b2eab8201e60335b56d1befff40c0f80263d64a169a8fd2e45");
    

    Fetching notifications

    Now that you've got your fetcher instance, it's time to fetch notifications, and display them!

    The inbox fetcher has several important methods:

    • getFetchedNotifications()
      This returns a copy of all the notifications that have been fetched. Useful for a list adapter.
      Warning: Calling this always makes a copy of the objects, so you should cache that method's result.
    • fetchNewNotifications()
      Allows you to fetch notifications that might have been received after the initial fetch. This is useful for implementing a refresh feature.
    • fetchNextPage()
      Fetches the next page of notifications. Batch will not fetch all notifications at once, but only small batches of them in pages.
      Use this method to load more notifications.
    • hasMore()
      Lets you know if more notifications might be available. Use this to make an infinite list, or a "load more" button.

    Note: BatchInboxFetcher and its methods are well documented using Javadoc. Unfortunately, Android Studio will not fetch it. Please use the web API Reference of BatchInboxFetcher to get detailed explanations about what every method does.

    BatchInboxFetcher will not fetch any notification by default, so before trying to display anything, you will need to call fetchNewNotifications() or fetchNextPage()

    Both fetch methods take a listener, which the SDK will call you back on either on failure, or success.
    Success callbacks include information about the operation to operate on the data, but you can very well do with the global methods.

    Note: By default, you will be called back on the thread that you called Batch.Inbox.getFetcher() on. Please see below if you want to change that behaviour.

    Reading notification content

    Once you've fetched notifications, you will end up with a list of BatchInboxNotificationContent objects.

    These objects have everything you need to display these notifications:

    • Title
    • Body
    • Send Date
    • Read state
    • Source (Campaign API/Dashboard or Transactional API)
    • Payload, in both Raw and Batch wrapped forms

    If you want to use advanced information about the notification, you can call getPushPayload(), which will return a BatchPushPayload instance.

    Just like with a custom receiver, this object allows you to fetch information, such as the deeplink, or big picture/large icon image URLs.

    Note: Just like when you get it using a broadcast receiver, the raw payload should be used carefully on keys you do not control:
    - "com.batch" is Batch's internal payload: You should not make any assumption about its content, nor depend on it. We reserve the right to change it at anytime, without warning.
    - Standard parsing good practices apply: Make sure to check every cast and handle errors gracefully, and never assume anything about the payload's content.

    Marking notifications as read

    Notifications can be marked as read in two ways:

    • By marking only one notification as read
      Use markAsRead(notification) with the notification you want to mark as read.
    • By marking all notifications as read
      Simply call markAllAsRead()

    In both cases, the notifications will be marked as read locally, but refreshing them might mark them as unread again, as the server might not have processed the request. These methods return quickly, and are thus safe to call on your UI thread.

    Note that notifications that have been opened when received are automatically marked as read.

    Tweaking the fetcher

    For more advanced usages, you can also change various aspects of the Inbox Fecther, such as:

    • The maximum number of notifications fetched per page (setMaxPageSize)
    • The maximum number of notifications that can be fetched using this object (setFetchLimit)
      A default limit is set to avoid going over memory by accident.
    • The handler that will be used to run the callbacks.
      By default, BatchInboxFetcher will call you back on the thread that you used to call Batch.Inbox.getFetcher(), but if for any reason you want to change the Handler used for callbacks, you should use setHandlerOverride()