Being notified about delivered push messages

Your application can be notified when the SDK receives a push message from the Bitplaces platform.

To register your application for this notification, you can use the provided BitplacesPushMessageBroadcastReceiver class that lets you register a callback which will be invoked with the corresponding BitplacesPushMessage object when a push message is received:

1
2
3
4
5
6
7
BitplacesPushMessageBroadcastReceiver pushMessageBroadcastReceiver = BitplacesPushMessageBroadcastReceiver.registerWithHandler(getApplicationContext(),
new BitplacesBroadcastHandler<BitplacesPushMessage>() {
    @Override
    public void onReceivedBroadcast(BitplacesPushMessage pushMessage) {
        Log.i(TAG, "Push notification received from Bitplaces");
    }
});

The BitplacesPushMessage object passed to your callback exposes the following getters to access its data:

Method Return value type Description
getMessageId() long Message ID on the Bitplaces platform. Use this ID to retrieve the complete message.
getMessageForeignId() String Your set foreign ID for this message
getBitplaceId() long ID (on the Bitplaces platform) of the bitplace associated with this message.
getBitplaceForeignId() String Your set foreign ID for the bitplace associated with this message
getContent() String Text content included with the push notification.

To unregister from this event you can just call the unregister method on the returned instance, passing to it your application context:

1
pushMessageBroadcastReceiver.unregister(getApplicationContext());

Letting the SDK show Push notifications

Instead of showing your own push notification, you can also let the Bitplaces SDK show the Push Notifications. By doing this, the Bitplaces SDK will show a notification for each push message. In addition, you can register your app for a callback, when the user clicks the notification and act accordingly. You may customize many features of this functionality, such as the color and icons to be used for the notifications.

Registering for Push Message Click Events

Start by registering a BroadcastReceiver for your application via the BitplacesPushMessageClickBroadcastReceiver class, that will be invoked, every time a user clicks on a push notification. This should be done in your custom Application-class. The BroadcastReceiver will receive a list of BitplacesPushMessages as the SDK provides functionality to bundle multiple message into one notification. If you do not use the grouping functionality, the list will contain only one message. The messages will be in ascending order, meaning that the first messages is the oldest and the last message is the most recent.

1
2
3
4
5
6
7
8
BitplacesPushMessageClickBroadcastReceiver receiver =
                BitplacesPushMessageClickBroadcastReceiver.registerWithHandler(getApplicationContext(),
                        new BitplacesBroadcastHandler<List<BitplacesPushMessage>>() {
                            @Override
                            public void onReceivedBroadcast(List<BitplacesPushMessage> bitplacesPushMessages) {
                                BitplacesLog.d(TAG, "Received messages: " + TextUtils.join(",", bitplacesPushMessages));
                            }
                        });

You can unregister the BroadcastReceiver via

1
receiver.unregister(getApplicationContext());

Customization of the push messages

For customizing the push notifications shown by the SDK, use the BitplacesPushNotificationSettings-class. Although only some features are mandatory, we recommend to also customize the other properties, such as the color, accordingly. All other field will use the default values of the device. A more detailed description of the features can be found in the Google API Guide for Notifications as well as the NotificationCompat-class.

Feature Description
Small Icon The small icon, that should be used for the notification. Setting this field is mandatory.
Large Icon The large icon, that should be used for the notification.
color The color, that should be used for the push notification.
indicatorColor The color of the indicator light, that is lit, when the user has unread notifications.
indicatorColorOnMs The duration the indicator light should be turned on.
indicatorColorOffMs The duration the indicator light should stay off.
title The title of a single push notification. Setting this field is mandatory.
groupedTitle The title for grouped push notifications.
vibrationPattern The vibration pattern to use, when a push notification arrives.
sound A custom sound file, that can be played, when a push notification arrives.

Instantiating and setting the BitplacesPushNotificationSettings is shown below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
BitplacesPushNotificationSettings settings = new BitplacesPushNotificationSettings.
                                    Builder("Notification Title", R.drawable.ic_push_notification_small) // e.g. your application name
                                    .setBundling(true)
                                    .setColor(0xFF0000)
                                    .setLargeIcon(R.drawable.ic_push_notification_large)
                                    .setGroupedTitle("Grouped Notification Title")
                                    .setVibrationPattern(new long[]{1000, 1000, 1000})
                                    .setIndicatorColor(ContextCompat.getColor(getApplicationContext(), R.color.bitplaces_accent), 200, 200)
                                    .create();

BitplacesSDK.getInstance().setNotificationsOnPushMessageSettings(settings);

Assigning the settings to the Bitplaces SDK automatically enables the push notifications. You want to temporarily, e.g. based on a user actions, change the push notifications status via

The push notifications can be disabled via:

1
BitplacesSDK.getInstance().setNotificationsOnPushMessageStatus(false);

To clear all visible push notifications, call:

1
BitplacesSDK.getInstance().clearAllPushNotifications();

Lastly, you can get the current status, whether push notifications are enabled via:

1
2
3
public boolean getNotificationsOnPushMessageEnabled() {
    return sdkParams.getPushNotificationsEnabled();
}

Bundeling

When the user receives many push messages at once, it may annoy the user. Therefore, the SDK provides a feature to bundle push messages into a single notification. Android 24 and later automatically provide this functionality via Builder.setGroup(). More information can be found here. Therefore, this setting only affects devices running Android API level 23 and lower. It can be en- or disabled via:

1
new BitplacesPushNotificationSettings.Builder().setBundling(true).create();

The grouped title will be used on all platforms to display a text for the collapsed summary notification. The example below uses Your Messages as GroupedTitle.

Push notification on Android API 23 and earlier:

Independent Bundled
Pre24 - Independent Pre24 - Bundled

Push notification on Android 24 and later:

Independent Bundled
Post24 - Independent Post24 - Bundled

Beware, that in the case for bundled messages on Android 23 and earlier, at maximum 10 lines can be used for listing the push messages. All other older messages will be cut off and will only be visible to the user in his Inbox.

Broadcast messaging

The Bitplaces platform supports a special type of message which is not connected to any particular bitplace: the broadcast message. They don't depend either on the bitplaces monitoring being active, and thus your application doesn't have to perform any aditional steps apart from initializing the SDK in order to be able to receive them.

Broadcast messages generate push notifications in the same way than other kinds of message. They can be retrieved from the inbox as regular messages and are encapsulated in BitplacesMessage instances. You can tell that a message is a broadcast message when its getEventType() method returns the value Broadcast (BitplaceEvent.EventType.Broadcast), instead of BitplaceIN, BitplaceOUT or UpdateRegion.

Because broadcast messages are not connected to any particular bitplace or to bitplaces monitoring itself, some of their methods such as getBitplaceId(), getForeignBitplaceId(), getTrackingMode(), getLatitude() and getLongitude() won't return any meaningful values.

Android 8 compatibility

Implementation of Push notifications in Android 8 requires the use of channels, please consult the Android 8 migration guide when setting up Push notifications Android 8