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.

∞ Returns

None

∞ Example

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

∞ .addDeviceInterest

Subscribes the device to the given interest.

∞ Arguments

∞ interestString Required

Interest that the device will be subscribed to.

∞ Returns

None

∞ Example

PushNotifications.addDeviceInterest("hello");

∞ .removeDeviceInterest

Unsubscribes the device from the given interest.

∞ Arguments

∞ interestString Required

Interest that the device will be unsubscribed from.

∞ Returns

None

∞ Example

PushNotifications.removeDeviceInterest("hello");

∞ .getDeviceInterests

Returns the interests the device is currently subscribed to.

∞ Arguments

None

∞ Returns

∞ interestsSet

Set of interests the device is currently subscribed to.

∞ Example

val interests = PushNotifications.getDeviceInterests();

Set<String> 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

∞ interestsSet Required

Set of new interests

∞ Returns

None

∞ Example

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

PushNotifications.setDeviceInterests(Arrays.asList("hello", "donuts").toSet());

∞ .clearDeviceInterests

Unsubscribes the device from all interests.

∞ Arguments

None

∞ Returns

None

∞ Example

PushNotifications.clearDeviceInterests();

∞ .setOnDeviceInterestsChangedListener

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

∞ Arguments

∞ listenerSubscriptionsChangedListener

Callback which will be fired when Device Interests change.

∞ Returns

None

∞ Example

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

PushNotifications.setOnDeviceInterestsChangedListener(new SubscriptionsChangedListener() {
  @Override
  public void onSubscriptionsChanged(Set<String> interests) {
    // do something magical 🔮
  }
});

∞ .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

∞ activityActivity

Activity for which this callback will trigger

∞ listenerPushNotificationReceivedListener

Callback which will be fired when a notification arrives.

∞ Returns

None

∞ Example

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

PushNotifications.setOnMessageReceivedListenerForVisibleActivity(this, new PushNotificationReceivedListener() {
  @Override
  public void onMessageReceived(RemoteMessage remoteMessage) {
      // do something magical 🔮
  }
});

∞ .setUserId

Sets the user id that is associated with this device. You can have up to 100 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

∞ userIdString Required

ID of the user you would like to associate with this device.

∞ tokenProviderTokenProvider Required

Token provider that will be used to generate the token for the user that you want to authenticate.

∞ callbackBeamsCallback Optional

Callback used to indicate whether the authentication process has succeeded.

∞ Returns

None

∞ Example

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()
        )
      }
    }
)
.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");
      }
    }
)

BeamsTokenProvider tokenProvider = new BeamsTokenProvider(
  "<YOUR_BEAMS_AUTH_URL_HERE>",
  new AuthDataGetter() {
    @Override
    public AuthData getAuthData() {
      // Headers and URL query params your auth endpoint needs to
      // request a Beams Token for a given user
      HashMap<String, String> headers = new HashMap<>();
      // for example:
      // headers.put("Authorization", sessionToken);
      HashMap<String, String> queryParams = new HashMap<>();
      return new AuthData(
        headers,
        queryParams
      );
    }
  }
);
PushNotifications.setUserId("<USER_ID_GOES_HERE>", tokenProvider, new BeamsCallback<Void, PusherCallbackError>(){
  @Override
  public void onSuccess(Void... values) {
      Log.i("PusherBeams", "Successfully authenticated with Pusher Beams");
  }

  @Override
  public void onFailure(PusherCallbackError error) {
      Log.i("PusherBeams", "Pusher Beams authentication failed: " + error.getMessage());
  }
});

∞ .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

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

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

∞ remoteMessageRemoteMessage

Object containing details of the incoming notification.

∞ Returns

None

∞ Example

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

public class MyCustomMessagingService extends MessagingService {
    @Override
    public void 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

∞ tokenString Required

New FCM device token.

∞ Returns

None

∞ Example

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

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

public class MyCustomMessagingService extends MessagingService {
  @Override
  public void onMessageReceived(RemoteMessage remoteMessage) {
    // We just got a notification 🔥
  }

  @Override
  public void onNewToken(String token) {
    super.onNewToken(token);
    // Incoming device token from FCM 🔒
  }
}