📘
See examples of method calls here.

Initialization methods

init

Initializes the SDK. Call this in the onCreate method of a class that extends Application.

Mindbox.init(
context: Context,
configuration: MindboxConfiguration,
listOf: List<MindboxPushService>
)

Usage examples:

No push notifications: Mindbox.init(applicationContext, configuration, listOf())
Firebase only: Mindbox.init(applicationContext, configuration, listOf(MindboxFirebase))

initPushServices

Initializes push services. Call this method in onCreate of your Application class if you call init in an Activity.

Mindbox.initPushServices(
  context = applicationContext,
  pushServices = listOf(MindboxFirebase)
)

updatePushToken

Passes the FCM token to the SDK. Call this method in onNewToken in a class that extends MessagingService.

Mindbox.updatePushToken(context: Context, token: String, pushService: MindboxPushService)

class FcmMessagingService : FirebaseMessagingService() {
    override fun onNewToken(token: String) {
        super.onNewToken(token)
        Mindbox.updatePushToken(applicationContext, token, MindboxFirebase)
    }
}

Retrieving data from the SDK

subscribeDeviceUuid and disposeDeviceUuidSubscription

subscribeDeviceUuid

Call this method to get a deviceUUID. This method requires a subscription to avoid any issues if called before the initialization of Mindbox SDK.
The value is returned as a string in the provided callback.

The ID returned by the subscribeDeviceUuid method can be used to unsubscribe from the callback.

Mindbox.subscribeDeviceUuid(
  context: Context,
  subscription: (String) → Unit
): String

Mindbox.disposeDeviceUuidSubscription(
  subscriptionId: String
)

val mySubscriptionid = Mindbox.subscribeDeviceUuid {
  deviceUUID -> Log.println(Log.INFO, "MindboxDeviceUUID", deviceUUID)
  }

Mindbox.disposeDeviceUuidSubscription(mySubscriptionid)

disposeDeviceUuidSubscription

Unsubscribes from deviceUUID updates. Accepts the identifier returned by the subscription method.

subscribePushTokens and disposePushTokenSubscription

subscribePushTokens

Call this method to get the FMS token. The method requires subscription to avoid any issues if called before initializing Mindbox SDK.
The value is returned to the provided callback as a JSON string in the following format:
{"FCM":"token1"}.

The subscribePushTokens method returns an ID to unsubscribe from a callback.

Mindbox.subscribePushTokens(
subscription: (String?) → Unit
): String

Mindbox.disposePushTokenSubscription(
subscriptionId: String
)

val mySubscriptionid = Mindbox.subscribePushTokens {
deviceUUID -> Log.println(Log.INFO, "Mindbox Push Token", deviceUUID)
}

Mindbox.disposePushTokenSubscription(mySubscriptionid)

disposePushTokenSubscription

Call this method to unsubscribe from the FMS token. The method accepts the ID returned by the subscription method.

getPushTokensSaveDate

Returns the save dates of FMS tokens as a map of key-value pairs (provider → timestamp).

Mindbox.getPushTokensSaveDate(): Map<String, Long>

getSdkVersion

Call this method to return an SDK version.

Mindbox.getSdkVersion(): String

Push notification event tracking

onPushReceived

🚧
Do not use this method if you are using handleRemoteMessage.

Mindbox.onPushReceived(
  context: Context,
  uniqKey: String
)

class MindboxMessagingService:FirebaseMessagingService() {

override fun onMessageReceived(remoteMessage: RemoteMessage) {

  val data = remoteMessage.data
  val uniqueKey = data["uniqueKey"]

  if (uniqueKey != null) {
    Mindbox.onPushReceived(applicationContext, uniqueKey)
  }
}

onPushClicked

Tracks a push notification click.

uniq_push_key — required. The push notification identifier.
uniq_push_button_key — optional. The button identifier. Pass this if the user clicked a button.

Mindbox.onPushClicked(
  context: Context,
  uniq_push_key: String,
  uniq_push_button_key: String
)

fun handleIntent(intent: Intent) {
val uniqKey = intent.getStringExtra("uniqKey");
val buttonUniqKey = intent.getStringExtra("buttonUniqKey"); 

if (uniqKey != null) {
  if (uniqKey != buttonUniqKey) {
    Mindbox.onPushClicked(applicationContext, uniqKey, buttonUniqKey  )
    }
  Mindbox.onPushClicked(applicationContext, uniqKey, ""  )
  } 
}

setLogLevel

To control what Mindbox SDK logs to the console, use setLogLevel to set the logging level.

Available values:

Level.NONE
Level.VERBOSE
Level.INFO
Level.DEBUG
Level.WARN
Level.ERROR

Logs are written in a debug build only. In the production environment, Mindbox SDK doesn’t write anything in the console.

Mindbox.setLogleve(level)

Event tracking

To pass events to Maestra, use the operations added to your project. You can run these operations in two modes:

async: once Maestra receives data, Maestra’s API returns the 200 status, and then processes data in the background,
sync: once Maestra receives data, Maestra’s API immediately starts processing the data and returns the actual processing status.

executeAsyncOperation

Call this method to execute async operations.

Mindbox.executeAsyncOperation(
  context = context,
  operationSystemName = "<system name of operation>",
  operationBody = <request body>
)

executeSyncOperation

Call this method to execute synced operations. The results are returned via callbacks.

Mindbox.executeSyncOperation(
  context: Context,
  operationSystemName: "<system name of operation>",
  operationBody: <request body>,
  onSuccess: (OperationResponse) -> Unit,
  onError: (MindboxError) -> Unit
)

Mindbox.executeSyncOperation(context: Context,
    operationSystemName: "<system name of operation>",
    operationBody: <request body>,
    classOfV: Class<V>,
    onSuccess: (V) -> Unit,
    onError: (MindboxError) -> Unit
): Unit

Retrieving clicks

When handling a click on a push notification rendered by handleRemoteMessage, you can retrieve the data that was included in that notification.

getUrlFromPushIntent

Returns the URL of the clicked push notification.
When a user clicks the push body, returns the body URL. When a user clicks a button, returns the button URL.
The URL is defined when setting up the push notification campaign in your project interface.

Mindbox.getUrlFromPushIntent(intent)

getPayloadFromPushIntent

Returns the payload of the clicked push notification. The data is defined when setting up the push notification campaign in your project interface.
The data is returned as a string. If the payload is JSON, deserialize it on your side.

Mindbox. getPayloadFromPushIntent(intent)

Other methods

setMessageHandling (since 2.6.1)

Defines how the SDK handles errors when loading notification images. You can use one of the built-in error handling strategies or implement a custom image loading strategy.
By default, the SDK uses applyDefaultStrategy — if an image fails to load, the push notification is shown without it.

fun setMessageHandling(
        imageFailureHandler: MindboxImageFailureHandler = PushNotificationManager.messageHandler.imageFailureHandler,
        imageLoader: MindboxImageLoader = PushNotificationManager.messageHandler.imageLoader,
    )

Error handling strategies

We provide 5 strategies:

cancellationStrategy
Use MindboxImageFailureHandler.cancellationStrategy(). If the image fails to load, the push notification is not shown.
applyDefaultStrategy
Use MindboxImageFailureHandler.applyDefaultStrategy(defaultImage). If the image fails to load, the SDK uses the default image specified in the constructor. If defaultImage is null, the push notification is shown without an image.
retryOrDefaultStrategy
Use MindboxImageFailureHandler.retryOrDefaultStrategy(maxAttempts, delay, defaultImage). If the image fails to load, the SDK retries up to max attempts times with the specified delay. If the image still fails to load, the push notification is shown with default Image, or without an image if default Image is null.
applyDefaultAndRetryStrategy
Use MindboxImageFailureHandler.applyDefaultAndRetryStrategy(maxAttempts, delay, defaultImage). If the image fails to load, the push notification is shown immediately with defaultImage (or without an image if defaultImage is null), while the SDK retries loading up to max attempts times with the specified delay. Requires minSdkLevel = M (23).
retryOrCancelStrategy
Use MindboxImageFailureHandler.retryOrCancelStrategy(maxAttempts, delay). If the image fails to load, the SDK retries up to max attempts times with the specified delay. If the image still fails to load, the push notification is not shown.

To apply a strategy, call Mindbox.setMessageHandling(imageFailureHandler = strategy) in Application.onCreate() or in your Activity.

class App: Application {
 
    override fun onCreate() {
        ...
        val defaultImage = ContextCompat.getDrawable(this, R.drawable.ic_placeholder)?.toBitmap()
        Mindbox.setMessageHandling(
                imageFailureHandler = MindboxImageFailureHandler.retryOrDefaultStrategy(
                    maxAttempts = 5,
                    delay = 3_000L,
                    defaultImage = defaultImage,
                ),
        )
        ...
    }
 
}

You can implement a custom strategy by implementing MindboxImageFailureHandler and overriding the onImageLoadingFailed method.

fun onImageLoadingFailed(  
    context: Context,  
    message: RemoteMessage,  
    state: MessageHandlingState,  
    error: Throwable,  
): ImageRetryStrategy

message: RemoteMessage — the model of the notification being displayed.

state: MessageHandlingState — contains the number of display attempts for this push notification and the isMessageDisplayed flag indicating whether the push notification has been shown.

Return one of the following ImageRetryStrategy values:

ImageRetryStrategy.Cancel — stop the process and do not show the push notification.
ImageRetryStrategy.ApplyDefault(defaultImage) — stop the loading process and show the push notification with the default image.
ImageRetryStrategy.Retry(delay) — retry loading the image after the specified delay.
ImageRetryStrategy.ApplyDefaultAndRetry(delay, defaultImage) — show the push notification with the default image (or without an image if defaultImage is null) and retry loading.

See the SDK source code for examples.

Image loading

We provide one built-in solution that makes a direct request to fetch the image. To use it, call MindboxImageLoader.default(). To apply it, call Mindbox.setMessageHandling(imageLoader = loader) in Application.onCreate() or in your Activity.

class App: Application {
 
    override fun onCreate() {
        ...
        Mindbox.setMessageHandling(
            imageLoader = MindboxImageLoader.default(),
        )
        ...
    }
 
}

You can implement a custom image loading strategy by implementing the MindboxImageLoader interface and overriding the onLoadImage method.

fun onLoadImage(
    context: Context,
    message: RemoteMessage,
    state: MessageHandlingState,
): Bitmap?

message: RemoteMessage — the model of the notification being displayed.

state: MessageHandlingState — contains the number of display attempts for this push notification and the isMessageDisplayed flag indicating whether the push notification has been shown. Load the image and return it as the method's result.

updateNotificationPermissionStatus (since 2.8.1)

Reports a change in the notification permission status.

 Mindbox.updateNotificationPermissionStatus(context:Context)

handleRemoteMessage

Renders a push notification.

🚧
If you use this method, do not call onPushReceived().

fun handleRemoteMessage(
        context: Context,
        message: Any?,
        channelId: String,
        channelName: String,
        @DrawableRes pushSmallIcon: Int,
        defaultActivity: Class<out Activity>,
        channelDescription: String? = null,
        activities: Map<String, Class<out Activity>>? = null,
    ): Boolean

isMindboxPush

Checks whether a push notification belongs to Maestra.

// For MindboxFirebase

fun isMindboxPush(remoteMessage: RemoteMessage): Boolean

fun isMindboxPush(remoteMessageData: Map<String, String>): Boolean

// For MindboxFirebase

fun isMindboxPush(remoteMessage: RemoteMessage): Boolean

convertToMindboxRemoteMessage

Converts a provider notification model to a Maestra notification model.

// For MindboxFirebase

fun convertToMindboxRemoteMessage(remoteMessage: RemoteMessage?): MindboxRemoteMessage?

fun convertToMindboxRemoteMessage(remoteMessageData: Map<String, String>): MindboxRemoteMessage?

// For MindboxFirebase

fun convertToMindboxRemoteMessage(remoteMessage: RemoteMessage?): MindboxRemoteMessage?

Changing the push notification icon color — pushSmallIcon (since 2.10.0)

To change the color of the monochrome icon, set the color in the mindbox_default_notification_color resource in res/values/colors.xml. Color changes may not work on some Android versions depending on the device manufacturer.

<color name="mindbox_default_notification_color">#FF0000</color> <!--Change the icon color to red-->

Enabling In-App display on DialogFragment (since 2.13.5)

To enable In-App display over a DialogFragment, add a boolean resource mindbox_support_inapp_on_fragment with the value true in res/values/bools.xml file.

 <bool name="mindbox_support_inapp_on_fragment">true</bool>

Android SDK classes

Mindbox
A singleton containing all public methods of the Mindbox SDK.

MindboxFirebase
A singleton responsible for the Firebase push notification provider. Can be used during initialization in Application via Mindbox.init(), or in initPushServices when initializing in an Activity.

MindboxError
Represents an error that occurred in the SDK. Can be returned when executing a synchronous operation.

InitializeMindboxException
Represents an error that occurred during SDK initialization. This exception is thrown if initialization fails.

PushAction
Stores information about a button in a push notification. Can be used as a model if you implement custom notification rendering.

RemoteMessage
Stores information about a push notification. Can be used as a model if you implement custom notification rendering.