Updated documentation with notification_state event (multiple mobile apps)

mino-dev1 · web-flow · commit fea401260846 · 2025-11-12T11:39:01.000+01:00
diff --git a/Documentation/authorization.md b/Documentation/authorization.md
@@ -173,6 +173,6 @@ class ExampleAuthProvider : AuthorizationProvider {
 ```kotlin
 configuration.applicationId = "<Your application id>" 
 ```
-Make sure your `applicationId` value matches exactly what you've defined in your Engagement project settings.
+Make sure your `applicationId` value matches exactly Application ID configured in your Bloomreach Engagement under **Project Settings > Campaigns > Channels > Push Notifications.**
 
 **Single mobile app:** If your Engagement project supports only one app, you can skip the `applicationId` configuration. The SDK will automatically use the default value "default-application".
diff --git a/Documentation/firebase.md b/Documentation/firebase.md
@@ -74,7 +74,15 @@ Next, you must create and register a service that extends `FirebaseMessagingServ
 
 The SDK will only handle push notification messages sent from the Engagement platform. A helper method `Exponea.isExponeaPushNotification()` is also provided.
 
-If you run the app, the SDK should the track push token to the Engagement platform. If you enabled the self-check, it will you inform you of this. Alternatively, you can find the customer in the Engagement web app and check the customer property `google_push_notification_id`.
+After running your application, the SDK tracks the push token to the Engagement platform. If you enabled the self-check feature, it will confirm successful tracking.
+You can also verify token tracking manually by locating the customer in the Bloomreach Engagement web application:
+
+- **SDK versions below 4.6.0:** Check the customer property `google_push_notification_id`
+- **SDK versions 4.6.0 and higher:** Check the `notification_state` event with property `push_notification_token`
+
+> ❗️Important
+>
+> SDK versions 4.6.0 and higher use event-based token tracking to support multiple mobile applications per project. Learn more about [Token tracking via notification_state event](https://documentation.bloomreach.com/engagement/docs/android-sdk-push-notifications#token-tracking-via-notification_state-event).
 
 A push token is typically generated at the first application start, but it has its own lifecycle. Your `FirebaseMessagingService` implementation is triggered only if a token is created or its value has changed. Please validate your expectations against the defined [token update triggers](https://firebase.google.com/docs/cloud-messaging/android/client#sample-register)
 
diff --git a/Documentation/huawei.md b/Documentation/huawei.md
@@ -83,7 +83,15 @@ Next, you must create and register a service that extends `HmsMessageService`. T
 
 The SDK will only handle push notification messages sent from the Engagement platform. A helper method `Exponea.isExponeaPushNotification()` is also provided.
 
-If you run the app, the SDK should the track push token to the Engagement platform. If you enabled the self-check, it will you inform you of this. Alternatively, you can find the customer in the Engagement web app and check the customer property `huawei_push_notification_id`.
+After running your application, the SDK tracks the push token to the Engagement platform. If you enabled the self-check feature, it will confirm successful tracking.
+You can also verify token tracking manually by locating the customer in the Bloomreach Engagement web application:
+
+- **SDK versions below 4.6.0:** Check the customer property `huawei_push_notification_id`
+- **SDK versions 4.6.0 and higher:** Check the `notification_state` event with property `push_notification_token`
+
+> ❗️Important
+>
+> SDK versions 4.6.0 and higher use event-based token tracking to support multiple mobile applications per project. Learn more about [Token tracking via notification_state event](https://documentation.bloomreach.com/engagement/docs/android-sdk-push-notifications#token-tracking-via-notification_state-event).
 
 A push token is typically generated at the first application start, but it has its own lifecycle. Your `HmsMessageService` implementation is triggered only if a token is created or its value has changed. Please validate your expectations against the defined [token update triggers](https://developer.huawei.com/consumer/en/doc/HMSCore-Guides/android-client-dev-0000001050042041#section487774626)
 
diff --git a/Documentation/push-notifications.md b/Documentation/push-notifications.md
@@ -92,6 +92,10 @@ By default, the SDK tracks push notifications automatically. In the [SDK configu
 
 If `automaticPushNotification` is enabled, the SDK will display push notifications from Engagement and track a "campaign" event for every delivered/opened push notification with the relevant properties.
 
+> ❗️Important
+>
+> SDK versions 4.6.0 and higher use event-based token tracking to support multiple mobile applications per project. Learn more about [Token tracking via notification_state event](#token-tracking-via-notification_state-event).
+
 ### Respond to push notifications
 
 When [creating a push notification](https://documentation.bloomreach.com/engagement/docs/mobile-push-notifications#creating-a-new-notification) in the Engagment web app, you can choose from three different actions to be performed when tapping the notification or additional buttons displayed with the notification.
@@ -249,6 +253,10 @@ Exponea.trackPushToken(
 
 Invoking this method will track the push token immediately regardless of the [SDK configuration](https://documentation.bloomreach.com/engagement/docs/android-sdk-configuration) for `tokenTrackFrequency`.
 
+> ❗️Important
+>
+> SDK versions 4.6.0 and higher use event-based token tracking to support multiple mobile applications per project. Learn more about [Token tracking via notification_state event](#token-tracking-via-notification_state-event).
+
 #### Track delivered push notification
 
 Use the [`trackDeliveredPush`](https://documentation.bloomreach.com/engagement/docs/android-sdk-tracking#track-push-notification-delivery-manually) method to manually track a delivered push notification:
@@ -356,6 +364,94 @@ Notification payloads use a JSON data structure.
 }
 ```
 
+## Token tracking via notification_state event
+
+Starting with SDK version 4.6.0, push notification tokens are tracked using `notification_state` events instead of customer
+profile properties. This change enables support for multiple mobile applications per project,
+allowing you to track multiple push tokens for the same customer across different apps and devices.
+
+### Token storage by SDK version
+
+#### SDK versions below 4.6.0:
+
+* Tokens are stored in customer profile properties: `google_push_notification_id` or `huawei_push_notification_id`
+* One token per customer profile
+* Single application per project
+
+#### SDK versions 4.6.0 and higher:
+
+* Tokens are stored as `notification_state` events
+* Multiple tokens per customer (grouped by Application ID)
+* Multiple applications per project supported
+* Backward compatibility maintained for Application ID `default-application`
+
+### When notification_state events are tracked
+
+The SDK automatically tracks `notification_state` events in the following scenarios:
+
+* SDK initialization
+* App transitions from background to foreground
+* New token received from Firebase or Huawei
+* Manual token tracking using `Exponea.trackPushToken(...)` or `Exponea.trackHmsPushToken(...)`
+* User anonymization via `Exponea.anonymize()`
+* Notification permission requested via `Exponea.requestPushAuthorization(...)`
+
+```kotlin
+Exponea.requestPushAuthorization(requireContext()) { granted ->
+    Logger.i(this, "Push notifications are allowed: $granted")
+}
+```
+
+The frequency of `notification_state` event tracking depends on the `tokenTrackFrequency` configuration property. [See SDK configuration](https://documentation.bloomreach.com/engagement/docs/android-sdk-configuration).
+
+### notification_state event properties
+
+| Property                | Description                              | Example values                          |
+|-------------------------|------------------------------------------|-----------------------------------------|
+| `push_notification_token` | Current push notification token          | Token string                            |
+| `platform`                | Mobile platform                          | `android` or `huawei`                       |
+| `valid`                   | Token validity status                    | `true` or `false`                           |
+| `description`             | Token state description                  | `Permission granted`, `Permission denied`, or `Invalidated` |
+| `application_id`          | Application identifier from SDK configuration | Custom ID or `default-application` (default) |
+| `device_id`               | Unique device identifier                 | UUID string                             |
+
+> 📘 Note
+>
+> If you don't specify an `application_id` in your SDK configuration, the default value `default-application` is used. [See SDK configuration](https://documentation.bloomreach.com/engagement/docs/android-sdk-configuration).
+
+### Understanding token states
+
+The combination of `valid` and `description` properties indicates the token's current state:
+
+| Valid | Description         | When this occurs                                                        |
+|-------|---------------------|------------------------------------------------------------------------|
+| `false` | `Invalidated`         | New token received \(old token becomes invalid\) or `Exponea.anonymize()` called |
+| `false` | `Permission denied`   | [requirePushAuthorization](https://documentation.bloomreach.com/engagement/docs/android-sdk-configuration) is `true` and user denied notification permission |
+| `true`  | `Permission granted`  | Valid token tracked successfully \(all other cases\)                     |
+
+### Configuring Application ID
+
+> 📘 Note
+>
+> See this section to configure `application_id`. [Configure Application ID](https://documentation.bloomreach.com/engagement/docs/android-sdk-setup#configure-application-id).
+
+> ❗️Important
+>
+> The SDK can automatically generate `notification_state` events,
+> but your Engagement project must have event creation enabled. If your project uses custom event schemas
+> or restricts event creation, add `notification_state` to the list of allowed events. Otherwise, push token registration will fail silently.
+
+### Verifying token tracking
+
+You can verify that tokens are being tracked correctly in the Bloomreach Engagement web application:
+
+1. Navigate to Data & Assets > Customers
+2. Locate the customer profile
+3. Check for `notification_state` events in the customer's event history
+4. Verify the `push_notification_token` property contains a valid token value 
+
+For SDK versions below 4.6.0, check the customer profile properties `google_push_notification_id` or `huawei_push_notification_id` instead.
+
 ## Troubleshooting
 
 > 📘
diff --git a/Documentation/setup.md b/Documentation/setup.md
@@ -98,7 +98,7 @@ Exponea.init(this, configuration)
 configuration.applicationId = "<Your application id>" 
 ```
 
-Make sure your `applicationId` value matches exactly what you've defined in your Engagement project settings.
+Make sure your `applicationId` value matches exactly Application ID configured in your Bloomreach Engagement under **Project Settings > Campaigns > Channels > Push Notifications.**
 
 **Single mobile app:** If your Engagement project supports only one app, you can skip the `applicationId` configuration. The SDK will automatically use the default value "default-application".
 
diff --git a/Documentation/tracking.md b/Documentation/tracking.md
@@ -13,6 +13,7 @@ By default, the SDK tracks certain events automatically, including:
 * Installation (after app installation and after invoking [anonymize](#anonymize))
 * User session start and end
 * Banner event for showing an in-app message or content block
+* `notification_state` event for push notification token tracking (SDK versions 4.6.0 and higher). [Learn more](https://documentation.bloomreach.com/engagement/docs/android-sdk-push-notifications#token-tracking-via-notification_state-event).
 
 Additionally, you can track any custom event relevant to your business.
 
@@ -195,6 +196,22 @@ Invoking this method will cause the SDK to:
 * Preload in-app messages, in-app content blocks, and app inbox for the new customer.
 * Track a new `installation` event for the new customer.
 
+#### How tokens are removed during anonymization
+
+The SDK removes push notification tokens differently depending on the version:
+
+**SDK versions below 4.6.0:**
+
+- Assigns an empty string to the `google_push_notification_id` or `huawei_push_notification_id` customer property
+
+**SDK versions 4.6.0 and higher:**
+
+- Tracks a `notification_state` event with `valid = false` and `description = Invalidated`
+
+> 📘 Note
+>
+> Learn more about [Token tracking via notification_state event](https://documentation.bloomreach.com/engagement/docs/android-sdk-push-notifications#token-tracking-via-notification_state-event).
+
 You can also use the `anonymize` method to switch to a different Engagement project. The SDK will then track events to a new customer record in the new project, similar to the first app session after installation on a new device.
 
 #### Examples
@@ -271,6 +288,10 @@ Invoking this method will track a push token immediately regardless of the value
 
 Each time the app becomes active, the SDK calls `verifyPushStatusAndTrackPushToken` and tracks the token.
 
+> 📘 Note
+>
+> SDK versions 4.6.0 and higher use event-based token tracking. Learn more about [Token tracking via notification_state event](https://documentation.bloomreach.com/engagement/docs/android-sdk-push-notifications#token-tracking-via-notification_state-event).
+
 #### Arguments
 
 | Name                 | Type    | Description |
diff --git a/Documentation/version-update.md b/Documentation/version-update.md
@@ -8,6 +8,42 @@ parentDocSlug: android-sdk-release-notes
 
 This guide will help you upgrade your Exponea SDK to the latest major version.
 
+## Update to version 4.6.0 or higher
+
+SDK versions 4.6.0 and higher support multiple mobile applications within a single Bloomreach Engagement project.
+
+This update introduces two major changes:
+
+### 1. **Application ID configuration**
+
+Each mobile application integrated with the SDK can now have its own unique `applicationId`. This identifier distinguishes between different applications within the same project.
+
+**When to configure Application ID:**
+
+- **Multiple mobile apps:** You must specify a unique `applicationId` for each app in the SDK configuration. The value must match the Application ID configured in Bloomreach Engagement under **Project Settings > Campaigns > Channels > Push Notifications.**
+- **Single mobile app:** If you use only one mobile application, you don't need to set `applicationId`. The SDK uses the default value `default-application` automatically.
+
+Learn more about [SDK configuration](https://documentation.bloomreach.com/engagement/docs/android-sdk-configuration) and [Configure Application ID](https://documentation.bloomreach.com/engagement/docs/android-sdk-setup#configure-application-id).
+
+### 2. **Push notification token tracking**
+
+Push notification tokens are now tracked using `notification_state` events instead of customer properties (`google_push_notification_id` or `huawei_push_notification_id`). This change enables tracking multiple push tokens for the same customer across different applications and devices.
+
+**Important prerequisites before upgrading:**
+
+The SDK automatically generates `notification_state` events. Before upgrading to version 4.6.0 or higher:
+
+- Ensure event creation is enabled for your Bloomreach Engagement project
+- If your project uses custom event schemas or restricts event creation, add `notification_state` to the list of allowed events
+- If your project blocks creation of new event types, push token registration will fail silently
+
+**Symptoms of blocked event creation:**
+
+- No new tokens appear in customer profiles or the event stream after SDK initialization
+- Push notifications are not delivered
+
+Learn more about [Token tracking via notification_state event](https://documentation.bloomreach.com/engagement/docs/android-sdk-push-notifications#token-tracking-via-notification_state-event).
+
 ## Update from version 3.x.x to 4.x.x
 
 Updating Exponea SDK to version 4 or higher requires making some changes related to in-app messages callback implementations.
@@ -182,4 +218,3 @@ has changed to
 > ❗️
 >
 > Invoking `Exponea.handleNewToken`, `Exponea.handleNewHmsToken`, and `Exponea.handleRemoteMessage` is allowed before SDK initialization in case it was initialized previously. In such a case, these methods will track events with the configuration of the last initialization. Please consider initializing the SDK in `Application::onCreate` to ensure a fresh configuration is applied in case of an update of your application.
-
