Kotlin / Java client SDK

PushNotifications

PushNotifications is the top-level entrypoint to the SDK. Methods are static, so can be accessed from anywhere in your project.

.start

Starts the SDK. Must be called at least once to ensure that the device is registered with Beams.

Arguments
None

Returns
None

Example

Kotlin / Java

PushNotifications.start(getApplicationContext(), "YOUR_INSTANCE_ID");

.addDeviceInterest

Subscribes the device to the given interest.

Arguments

  • interest(string): Interest that the device will be subscribed to.

Returns
None

Example

Kotlin / Java

PushNotifications.addDeviceInterest("hello");

.removeDeviceInterest

Unsubscribes the device from the given interest.

Arguments

  • interest(string): Interest that the device will be unsubscribed from.

Returns
None

Example

Kotlin / Java

PushNotifications.removeDeviceInterest("hello");

.getDeviceInterests

Returns the interests the device is currently subscribed to.

Arguments
None

Returns
interests(Set<String>): Set of interests the device is currently subscribed to.

Example

  • Kotlin
  • Java

Kotlin

val interests = PushNotifications.getDeviceInterests();

.setDeviceInterests

Sets the subscriptions state for the device. Any interests not in the set will be unsubscribed from, so this will replace the Interest set by the one provided.

Arguments

  • interests(Set<String>): Set of new interests

Returns
None

Example

  • Kotlin
  • Java

Kotlin

PushNotifications.setDeviceInterests(setOf("hello", "donuts"))

.clearDeviceInterests

Unsubscribes the device from all interests.

Arguments
None

Returns
None

Example

Kotlin / Java

PushNotifications.clearDeviceInterests();

.setOnDeviceInterestsChangedListener

Sets a callback which will be fired whenever Device Interests are changed.

Arguments

  • listener(SubscriptionsChangedListener): Callback which will be fired when Device Interests change.

Returns
None

Example

  • Kotlin
  • Java

Kotlin

PushNotifications.setOnDeviceInterestsChangedListener(object: SubscriptionsChangedListener {
  override fun onSubscriptionsChanged(interests: Set<String>) {
    // do something wonderful 🌈
  }
})

.setOnMessageReceivedListenerForVisibleActivity

Configures the listener that handles a remote message only when this activity is in the foreground. You can use this method to update your UI. This should be called from the Activity.onResume method.

Arguments

  • activity(Activity): Activity for which this callback will trigger
  • listener(PushNotificationReceivedListener): Callback which will be fired when a notification arrives.

Returns
None

Example

  • Kotlin
  • Java

Kotlin

PushNotifications.setOnMessageReceivedListenerForVisibleActivity(this, object: PushNotificationReceivedListener {
  override fun onMessageReceived(remoteMessage: RemoteMessage) {
    // do something wonderful 🌈
} })

.setUserId

Sets the user id that is associated with this device. You can have up to 10 devices associated with a given user.

This method can only be called after start. Once a user ID has been set for the device it cannot be changed until clearAllState or stop have been called.

Arguments

  • userId(String): ID of the user you would like to associate with this device.
  • tokenProvider(TokenProvider): Token provider that will be used to generate the token for the user that you want to authenticate.
  • callback(BeamsCallback | Optional): Callback used to indicate whether the authentication process has succeeded.

Returns
None

Example

  • Kotlin
  • Java

Kotlin

val tokenProvider = BeamsTokenProvider(
    "<YOUR_BEAMS_AUTH_URL_HERE>",
    object: AuthDataGetter {
      override fun getAuthData(): AuthData {
        return AuthData(
            // Headers and URL query params your auth endpoint needs to
            // request a Beams Token for a given user
            headers = hashMapOf(
                // for example:
                // "Authorization" to sessionToken
            ),
            queryParams = hashMapOf()
        )
      }
    }
)

PushNotifications.setUserId(
    "<USER_ID_GOES_HERE>",
    tokenProvider,
    object : BeamsCallback<Void, PusherCallbackError> {
      override fun onFailure(error: PusherCallbackError) {
        Log.e("BeamsAuth", "Could not login to Beams: ${error.message}");
      }

      override fun onSuccess(vararg values: Void) {
        Log.i("BeamsAuth", "Beams login success");
      }
    }
)

.clearAllState

Clears all the state in the SDK, leaving it in a empty started state. You should call this method when your user logs out of the application.

If the device was paired with a user and the app is uninstalled without calling this method, Pusher Beams will remove the device. This can take up to 3 days to take effect.

Arguments
None

Returns
None

Example

Kotlin / Java

PushNotifications.clearAllState();

.stop

Stops the SDK by deleting all state (both locally and remotely). Calling this will mean the device will cease to receive push notifications.start must be called if you want to use the SDK again.

Arguments
None

Returns
None

Example

Kotlin / Java

PushNotifications.stop();

MessagingService

MessagingService is an Android Service base class that can be extended to handle data coming from FCM such as incoming notifications and the FCM device token.

.onMessageReceived

Callback used to inform the service of incoming push notifications.

Arguments

  • remoteMessage(RemoteMessage): Object containing details of the incoming notification.

Returns
None

Example

  • Kotlin
  • Java

Kotlin

class MyCustomMessagingService: MessagingService() {
  override fun onMessageReceived(remoteMessage: RemoteMessage) {
    // We just got a notification 🔥
  }
}

.onNewToken

Callback used to inform the service when the device gets a new FCM device token. You can use this token to integrate with other push notification services. This token has already been passed to the Beams SDK no further action is required.

Arguments

  • token(String): New FCM device token.

Returns
None

Example

  • Kotlin
  • Java

Kotlin

class MyCustomMessagingService: MessagingService() {
  override fun onMessageReceived(remoteMessage: RemoteMessage) {
    // We just got a notification 🔥
  }

  override fun onNewToken(remoteMessage: RemoteMessage) {
    // Incoming device token from FCM 🔒
  }
}