cordova-plugin-reteno 2.2.0 → 2.2.2

package/docs/api.md

@@ -1,734 +0,0 @@
-## API
-
-Notes:
-
-- Recommended: call `RetenoPlugin.init(...)` once on app startup before calling SDK-dependent methods like `logEvent`, `setUserAttributes`, `setAnonymousUserAttributes`, or `setDeviceToken`.
-- As a convenience, the JS wrapper will auto-call init when you call those methods, but explicit init gives you clearer error handling and predictable timing.
-- All methods that call native code return a `Promise`. Optional `success` / `error` callbacks are still supported for backward compatibility.
-- Android SDK support: see the current Reteno Android SDK compatibility in release notes.
-- Push deeplinks: Reteno can deliver links in push payloads, but routing them to the correct screen in a hybrid app usually requires a separate deeplink solution (for example, Branch.io, custom URL schemes, or Universal/App Links handling in the host app).
-
-### Initialization
-
-| Method                                                           | Supported platform | Description                                                                                                                                                                                                                                                                                                                                                          |
-| ---------------------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [init](../www/cordova-plugin-reteno.js)                          | iOS, Android       | Initializes Reteno SDK. Accepts optional `RetenoInitializeOptions` with `accessKey`, `pauseInAppMessages`, `pausePushInAppMessages`, `inAppMessagesPauseBehaviour` (iOS), `lifecycleTrackingOptions`, `sessionDurationSeconds` (Android 2.9.6+, iOS 2.7.2+), `isAutomaticScreenReportingEnabled` (iOS; see note below) and `isDebugMode`. [Types](../types/index.ts) |
-| [requestNotificationPermission](../www/cordova-plugin-reteno.js) | iOS, Android       | Requests push permission (iOS) or `POST_NOTIFICATIONS` (Android 13+). Returns `0` or `1` on Android (`RequestNotificationPermissionResult`) in [types](../types/index.ts).                                                                                                                                                                                           |
-| [setLifecycleTrackingOptions](../www/cordova-plugin-reteno.js)   | iOS, Android       | Configures automatic tracking for app lifecycle, push subscription, and session events. Android: applies immediately. iOS: supported only before initialization (stored and applied during `init(...)`). [Types](../types/index.ts)                                                                                                                                  |
-
-### User data
-
-| Method                                                           | Supported platform | Description                                                                                                             |
-| ---------------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
-| [setUserAttributes](../www/cordova-plugin-reteno.js)             | iOS, Android       | Supports `marketId` with the bundled Android 2.9.6+ and iOS 2.7.2+ SDKs. Pass `""` to clear. [Types](../types/index.ts) |
-| [setAnonymousUserAttributes](../www/cordova-plugin-reteno.js)    | iOS, Android       | Supports `marketId` with the bundled Android 2.9.6+ and iOS 2.7.2+ SDKs. Pass `""` to clear. [Types](../types/index.ts) |
-| [setMultiAccountUserAttributes](../www/cordova-plugin-reteno.js) | iOS, Android       | Supports `marketId` with the bundled Android 2.9.6+ and iOS 2.7.2+ SDKs. Pass `""` to clear. [Types](../types/index.ts) |
-
-### Event tracking
-
-| Method                                               | Supported platform | Description                                                                                                                     |
-| ---------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
-| [logEvent](../www/cordova-plugin-reteno.js)          | iOS, Android       | [Types](../types/index.ts)                                                                                                      |
-| [logEcommerceEvent](../www/cordova-plugin-reteno.js) | iOS, Android       | Tracks ecommerce activity (product views, cart updates, orders, search requests, etc.). [Types](../types/index.ts)              |
-| [logScreenView](../www/cordova-plugin-reteno.js)     | iOS, Android       | Logs a screen view for manual tracking.                                                                                         |
-| [forcePushData](../www/cordova-plugin-reteno.js)     | iOS, Android       | Forces Reteno to sync queued data. On iOS the plugin performs a technical `logEvent(..., forcePush: true)` call under the hood. |
-
-### Push notifications
-
-| Method                                                                       | Supported platform | Description                                                                                                                                                                                                                                                                                                                                                                       |
-| ---------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [setDeviceToken](../www/cordova-plugin-reteno.js)                            | iOS, Android       | Forwards the device token to Reteno (use when another plugin owns push callbacks/token, e.g. Firebasex messaging enabled).                                                                                                                                                                                                                                                        |
-| [getInitialNotification](../www/cordova-plugin-reteno.js)                    | iOS, Android       | Returns push notification that triggered creating app instance.                                                                                                                                                                                                                                                                                                                   |
-| [setOnRetenoPushReceivedListener](../www/cordova-plugin-reteno.js)           | iOS, Android       | Sets listener for newly received push notification.                                                                                                                                                                                                                                                                                                                               |
-| [removeOnRetenoPushReceivedListener](../www/cordova-plugin-reteno.js)        | iOS, Android       | Removes listener for push notification received events.                                                                                                                                                                                                                                                                                                                           |
-| [setOnRetenoNotificationClickedListener](../www/cordova-plugin-reteno.js)    | iOS, Android       | Sets listener for notification click events.                                                                                                                                                                                                                                                                                                                                      |
-| [removeOnRetenoNotificationClickedListener](../www/cordova-plugin-reteno.js) | iOS, Android       | Removes listener for notification click events.                                                                                                                                                                                                                                                                                                                                   |
-| [setOnRetenoPushDismissedListener](../www/cordova-plugin-reteno.js)          | Android            | Sets listener for push dismissed (swipe) events.                                                                                                                                                                                                                                                                                                                                  |
-| [removeOnRetenoPushDismissedListener](../www/cordova-plugin-reteno.js)       | Android            | Removes listener for push dismissed (swipe) events.                                                                                                                                                                                                                                                                                                                               |
-| [setOnRetenoCustomPushReceivedListener](../www/cordova-plugin-reteno.js)     | Android            | Sets listener for custom push received events.                                                                                                                                                                                                                                                                                                                                    |
-| [removeOnRetenoCustomPushReceivedListener](../www/cordova-plugin-reteno.js)  | Android            | Removes listener for custom push received events.                                                                                                                                                                                                                                                                                                                                 |
-| [setOnRetenoPushButtonClickedListener](../www/cordova-plugin-reteno.js)      | iOS, Android       | Sets listener for push notification action button click events. Emits `reteno-push-button-clicked`. [Types](../types/index.ts)                                                                                                                                                                                                                                                    |
-| [removeOnRetenoPushButtonClickedListener](../www/cordova-plugin-reteno.js)   | iOS, Android       | Removes listener for push notification action button click events.                                                                                                                                                                                                                                                                                                                |
-| [setNotificationActionHandler](../www/cordova-plugin-reteno.js)              | iOS, Android       | On iOS, installs the native action button handler when both `enabled` (default: `true`) and `emitEvent` are true — e.g. `{ emitEvent: true }` or `{ enabled: true, emitEvent: true }`. Any other value (e.g. `false`, `null`, `true`, `{ enabled: true }`) clears the handler. On Android, this is a no-op (button clicks are detected automatically). [Types](../types/index.ts) |
-| [setWillPresentNotificationOptions](../www/cordova-plugin-reteno.js)         | iOS                | Sets presentation options for foreground notifications. Optionally emits `reteno-push-received`. [Types](../types/index.ts)                                                                                                                                                                                                                                                       |
-| [setDidReceiveNotificationResponseHandler](../www/cordova-plugin-reteno.js)  | iOS                | Enables a response handler for notification taps. Optionally emits `reteno-notification-clicked`. [Types](../types/index.ts)                                                                                                                                                                                                                                                      |
-| [updateDefaultNotificationChannel](../www/cordova-plugin-reteno.js)          | Android            | Updates the default notification channel name and description for existing users. [Types](../types/index.ts)                                                                                                                                                                                                                                                                      |
-| [setNotificationGroupingRule](../www/cordova-plugin-reteno.js)               | Android            | Groups notifications by a push payload field or a constant group ID. The rule is persisted natively and restored before background push handling. Pass `null` to disable. [Types](../types/index.ts)                                                                                                                                                                              |
-
-### In-app messages
-
-Bundled native SDKs support the `DOES_NOT_EQUAL` in-app rule condition: Android SDK 2.9.6+ and iOS SDK 2.7.2+.
-
-| Method                                                                            | Supported platform | Description                                                                                                                                                       |
-| --------------------------------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [pauseInAppMessages](../www/cordova-plugin-reteno.js)                             | iOS, Android       | Pauses or resumes in-app messages at runtime. Pass `true` to pause, `false` to resume.                                                                            |
-| [setInAppMessagesPauseBehaviour](../www/cordova-plugin-reteno.js)                 | iOS, Android       | Sets how paused in-app messages are handled: `SKIP_IN_APPS` or `POSTPONE_IN_APPS`. [Types](../types/index.ts)                                                     |
-| [setOnInAppLifecycleCallback](../www/cordova-plugin-reteno.js)                    | iOS, Android       | Subscribes to in-app status/lifecycle events (beforeDisplay, onDisplay, beforeClose, afterClose, onError). Pass `null` to unsubscribe. [Types](../types/index.ts) |
-| [setOnInAppMessageCustomDataReceivedListener](../www/cordova-plugin-reteno.js)    | Android            | Sets listener for in-app message custom data events.                                                                                                              |
-| [removeOnInAppMessageCustomDataReceivedListener](../www/cordova-plugin-reteno.js) | Android            | Removes listener for in-app message custom data events.                                                                                                           |
-
-### App Inbox
-
-| Method                                                             | Supported platform | Description                                                                                                |
-| ------------------------------------------------------------------ | ------------------ | ---------------------------------------------------------------------------------------------------------- |
-| [getAppInboxMessages](../www/cordova-plugin-reteno.js)             | iOS, Android       | Fetches App Inbox messages with pagination. Returns `{ messages, totalPages }`. [Types](../types/index.ts) |
-| [getAppInboxMessagesCount](../www/cordova-plugin-reteno.js)        | iOS, Android       | Fetches count of App Inbox messages. Returns a number.                                                     |
-| [subscribeOnMessagesCountChanged](../www/cordova-plugin-reteno.js) | iOS, Android       | Subscribes to App Inbox messages count changes.                                                            |
-| [unsubscribeMessagesCountChanged](../www/cordova-plugin-reteno.js) | iOS, Android       | Unsubscribes from App Inbox messages count changes.                                                        |
-| [markAsOpened](../www/cordova-plugin-reteno.js)                    | iOS, Android       | Marks an App Inbox message as opened.                                                                      |
-| [markAllMessagesAsOpened](../www/cordova-plugin-reteno.js)         | iOS, Android       | Marks all App Inbox messages as opened.                                                                    |
-
-### Recommendations
-
-| Method                                                | Supported platform | Description                                                                                          |
-| ----------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------- |
-| [getRecommendations](../www/cordova-plugin-reteno.js) | iOS, Android       | Fetches product or category recommendations. Returns `{ recoms: [...] }`. [Types](../types/index.ts) |
-| [logRecommendations](../www/cordova-plugin-reteno.js) | iOS, Android       | Sends recommendation impressions or clicks. [Types](../types/index.ts)                               |
-
-### init example
-
-Initialize the Reteno SDK with optional configuration. Payload type: `RetenoInitializeOptions` in [types](../types/index.ts).
-
-```js
-// Initialize with default options (in-app messages enabled).
-RetenoPlugin.init()
-  .then(() => console.log('init: OK'))
-  .catch((err) => console.error('init: ERROR', err));
-```
-
-```js
-// Initialize with in-app messages paused and lifecycle tracking configured.
-// pauseInAppMessages: pauses all in-app messages until resumed.
-// pausePushInAppMessages: pauses in-app messages triggered by push notifications.
-// inAppMessagesPauseBehaviour: (iOS) defines handling while paused: 'SKIP_IN_APPS' or 'POSTPONE_IN_APPS'.
-// lifecycleTrackingOptions: configures app lifecycle, push subscription, and session event tracking ('ALL', 'NONE', or an object).
-// sessionDurationSeconds (Android 2.9.6+, iOS 2.7.2+): optional session reset duration.
-// isAutomaticScreenReportingEnabled: enables automatic native screen view tracking on iOS.
-//   Keep this false in Cordova/Ionic WebView apps (including Android demos).
-//   Defaults to false. Note: in Cordova/Ionic apps the UI runs inside a single WebView,
-//   so automatic tracking captures native UIViewController transitions (e.g. CDVViewController),
-//   NOT your JS screen navigations. For meaningful screen tracking, use logScreenView()
-//   manually (e.g. by subscribing to your router's navigation events).
-//   On Android the native SDK tracks Fragment transitions, which is equally irrelevant
-//   in a WebView-based app — use logScreenView() instead.
-// isDebugMode: enables debug mode for near real-time event monitoring in the Reteno dashboard.
-//   Use only with test devices or developer accounts.
-RetenoPlugin.init({
-  pauseInAppMessages: true,
-  pausePushInAppMessages: false,
-  inAppMessagesPauseBehaviour: 'SKIP_IN_APPS', // iOS
-  isAutomaticScreenReportingEnabled: false, // keep false for hybrid/WebView apps
-  isDebugMode: true, // enables debug mode
-  sessionDurationSeconds: 30 * 60, // Android 2.9.6+, iOS 2.7.2+: 30 minutes
-  lifecycleTrackingOptions: {
-    appLifecycleEnabled: true,
-    foregroundLifecycleEnabled: false,
-    pushSubscriptionEnabled: true,
-    sessionStartEventsEnabled: true,
-    sessionEndEventsEnabled: false,
-  },
-})
-  .then(() => console.log('init: OK'))
-  .catch((err) => console.error('init: ERROR', err));
-```
-
-```js
-// Shorthand lifecycle tracking values:
-RetenoPlugin.init({ lifecycleTrackingOptions: 'ALL' });
-RetenoPlugin.init({ lifecycleTrackingOptions: 'NONE' });
-// Legacy alias (deprecated): sessionEventsEnabled controls both start/end at once.
-RetenoPlugin.init({ lifecycleTrackingOptions: { sessionEventsEnabled: false } });
-```
-
-### setUserAttributes payload example
-
-```js
-// `externalUserId` is required and must be a non-empty string.
-// `user` is optional (you can omit it or pass null).
-RetenoPlugin.setUserAttributes({
-  externalUserId: 'user-123',
-  user: {
-    userAttributes: {
-      email: 'john.doe@example.com',
-      phone: '+1234567890',
-      firstName: 'John',
-      lastName: 'Doe',
-      languageCode: 'en',
-      timeZone: 'Europe/Kyiv',
-      address: {
-        region: 'Kyivska',
-        town: 'Kyiv',
-        address: 'Khreshchatyk St, 1',
-        postcode: '01001',
-      },
-      fields: [{ key: 'plan', value: 'premium' }],
-      marketId: 'market_1',
-    },
-    subscriptionKeys: ['news', 'promotions'],
-    groupNamesInclude: ['beta-testers'],
-    groupNamesExclude: ['unsubscribed'],
-  },
-})
-  .then(() => console.log('setUserAttributes: OK'))
-  .catch((err) => console.error('setUserAttributes: ERROR', err));
-```
-
-### setAnonymousUserAttributes payload example
-
-```js
-// Anonymous attributes are used before contact identification.
-// Note: Unlike setUserAttributes, this payload does NOT include phone/email.
-RetenoPlugin.setAnonymousUserAttributes({
-  firstName: 'John',
-  lastName: 'Doe',
-  languageCode: 'en',
-  timeZone: 'Europe/Kyiv',
-  address: {
-    region: 'Kyivska',
-    town: 'Kyiv',
-    address: 'Khreshchatyk St, 1',
-    postcode: '01001',
-  },
-  fields: [{ key: 'utm_source', value: 'google' }],
-  marketId: 'market_1',
-})
-  .then(() => console.log('setAnonymousUserAttributes: OK'))
-  .catch((err) => console.error('setAnonymousUserAttributes: ERROR', err));
-```
-
-### setMultiAccountUserAttributes payload example
-
-```js
-// Since 2.8.0 it is possible to share push notification token between user accounts.
-// If it is required to receive push notifications on accounts that aren't currently logged in,
-// but they share the same device, always use setMultiAccountUserAttributes instead of setUserAttributes.
-// If you want to switch back to default behavior, just replace usages of
-// setMultiAccountUserAttributes to setUserAttributes. This will roll back to
-// 1 token per device behavior.
-// `externalUserId` is required and must be a non-empty string.
-// `user` is required and must be an object.
-RetenoPlugin.setMultiAccountUserAttributes({
-  externalUserId: 'user-123',
-  user: {
-    userAttributes: {
-      email: 'john.doe@example.com',
-      phone: '+1234567890',
-      firstName: 'John',
-      lastName: 'Doe',
-      languageCode: 'en',
-      timeZone: 'Europe/Kyiv',
-      address: {
-        region: 'Kyivska',
-        town: 'Kyiv',
-        address: 'Khreshchatyk St, 1',
-        postcode: '01001',
-      },
-      fields: [{ key: 'plan', value: 'premium' }],
-      marketId: 'market_1',
-    },
-    subscriptionKeys: ['news', 'promotions'],
-    groupNamesInclude: ['beta-testers'],
-    groupNamesExclude: ['unsubscribed'],
-  },
-})
-  .then(() => console.log('setMultiAccountUserAttributes: OK'))
-  .catch((err) => console.error('setMultiAccountUserAttributes: ERROR', err));
-```
-
-### setLifecycleTrackingOptions example
-
-```js
-// Enable/disable specific lifecycle tracking features.
-// Unspecified fields default to true.
-// Android: applies immediately.
-// iOS: this works only BEFORE SDK initialization (before calling init()).
-// Deprecated: sessionEventsEnabled (if used) toggles both sessionStart and sessionEnd.
-RetenoPlugin.setLifecycleTrackingOptions({
-  sessionStartEventsEnabled: true,
-  sessionEndEventsEnabled: true,
-})
-  .then(() => console.log('setLifecycleTrackingOptions: OK'))
-  .catch((err) => console.error('setLifecycleTrackingOptions: ERROR', err));
-```
-
-```js
-// Convenience values:
-RetenoPlugin.setLifecycleTrackingOptions('ALL');
-RetenoPlugin.setLifecycleTrackingOptions('NONE');
-```
-
-If `init()` has already started/completed on iOS, `setLifecycleTrackingOptions(...)` returns an error.
-Invalid values (anything except `'ALL'`, `'NONE'`, or an object with known fields) return an error.
-
-### logEvent payload example
-
-Payload type: `LogEventPayload` in [types](../types/index.ts).
-
-```js
-RetenoPlugin.logEvent({
-  eventName: 'purchase',
-  // Optional ISO 8601 string. If omitted, current time is used.
-  date: new Date().toISOString(),
-  parameters: [
-    { name: 'orderId', value: 'A-123' },
-    { name: 'amount', value: '19.99' },
-  ],
-})
-  .then(() => console.log('logEvent: OK'))
-  .catch((err) => console.error('logEvent: ERROR', err));
-```
-
-### logEcommerceEvent examples
-
-Tracks ecommerce activity. Payload type: `LogEcommerceEventPayload` in [types](../types/index.ts).
-Supported event types: `productViewed`, `productCategoryViewed`, `productAddedToWishlist`, `cartUpdated`, `orderCreated`, `orderUpdated`, `orderDelivered`, `orderCancelled`, `searchRequest`.
-
-See also: [Reteno ecommerce activity tracking](https://docs.reteno.com/reference/android-ecommerce-activity-tracking).
-
-```js
-// Product viewed
-RetenoPlugin.logEcommerceEvent({
-  eventType: 'productViewed',
-  product: {
-    productId: 'SKU-123',
-    price: 29.99,
-    isInStock: true,
-    attributes: [{ name: 'color', value: ['red', 'blue'] }],
-  },
-  currencyCode: 'USD',
-})
-  .then(() => console.log('logEcommerceEvent: OK'))
-  .catch((err) => console.error('logEcommerceEvent: ERROR', err));
-```
-
-```js
-// Cart updated
-RetenoPlugin.logEcommerceEvent({
-  eventType: 'cartUpdated',
-  cartId: 'cart-456',
-  products: [
-    {
-      productId: 'SKU-123',
-      quantity: 2,
-      price: 29.99,
-      name: 'T-Shirt',
-      category: 'Apparel',
-    },
-  ],
-  currencyCode: 'USD',
-})
-  .then(() => console.log('logEcommerceEvent: OK'))
-  .catch((err) => console.error('logEcommerceEvent: ERROR', err));
-```
-
-```js
-// Order created
-RetenoPlugin.logEcommerceEvent({
-  eventType: 'orderCreated',
-  order: {
-    externalOrderId: 'ORD-789',
-    totalCost: 59.98,
-    status: 'INITIALIZED',
-    date: new Date().toISOString(),
-    items: [
-      {
-        externalItemId: 'SKU-123',
-        name: 'T-Shirt',
-        category: 'Apparel',
-        quantity: 2,
-        cost: 29.99,
-        url: 'https://example.com/products/SKU-123',
-      },
-    ],
-  },
-  currencyCode: 'USD',
-})
-  .then(() => console.log('logEcommerceEvent: OK'))
-  .catch((err) => console.error('logEcommerceEvent: ERROR', err));
-```
-
-```js
-// Search request
-RetenoPlugin.logEcommerceEvent({
-  eventType: 'searchRequest',
-  search: 'red t-shirt',
-  isFound: true,
-})
-  .then(() => console.log('logEcommerceEvent: OK'))
-  .catch((err) => console.error('logEcommerceEvent: ERROR', err));
-```
-
-### logScreenView example
-
-```js
-RetenoPlugin.logScreenView('HomeScreen')
-  .then(() => console.log('logScreenView: OK'))
-  .catch((err) => console.error('logScreenView: ERROR', err));
-```
-
-### forcePushData example
-
-```js
-RetenoPlugin.forcePushData()
-  .then(() => console.log('forcePushData: OK'))
-  .catch((err) => console.error('forcePushData: ERROR', err));
-```
-
-On iOS, `forcePushData()` is implemented through a technical `logEvent` call with `forcePush: true`.
-
-### pauseInAppMessages example
-
-Pause or resume in-app messages at runtime.
-
-```js
-// Pause in-app messages
-RetenoPlugin.pauseInAppMessages(true)
-  .then(() => console.log('pauseInAppMessages: paused'))
-  .catch((err) => console.error('pauseInAppMessages: ERROR', err));
-
-// Resume in-app messages
-RetenoPlugin.pauseInAppMessages(false)
-  .then(() => console.log('pauseInAppMessages: resumed'))
-  .catch((err) => console.error('pauseInAppMessages: ERROR', err));
-```
-
-### setInAppMessagesPauseBehaviour example
-
-Configure how paused in-app messages are handled. Type: `InAppPauseBehaviour` in [types](../types/index.ts).
-On iOS, you can also preconfigure this during `init(...)` via `inAppMessagesPauseBehaviour`.
-
-```js
-// Discard messages received while paused
-RetenoPlugin.setInAppMessagesPauseBehaviour('SKIP_IN_APPS')
-  .then(() => console.log('setInAppMessagesPauseBehaviour: OK'))
-  .catch((err) => console.error('setInAppMessagesPauseBehaviour: ERROR', err));
-
-// Save the first queued message and display it when unpaused
-RetenoPlugin.setInAppMessagesPauseBehaviour('POSTPONE_IN_APPS')
-  .then(() => console.log('setInAppMessagesPauseBehaviour: OK'))
-  .catch((err) => console.error('setInAppMessagesPauseBehaviour: ERROR', err));
-```
-
-### setOnInAppLifecycleCallback example
-
-Subscribe to in-app message status/lifecycle events. The listener receives events with `event` (lifecycle stage) and `data` (context-specific payload). Types: `InAppLifecyclePayload`, `InAppData`, `InAppCloseData`, `InAppErrorData` in [types](../types/index.ts).
-
-```js
-function onInAppStatus(event) {
-  var detail = event.detail || event;
-  console.log('In-app status:', detail.event, detail.data);
-  // detail.event is one of: 'beforeDisplay', 'onDisplay', 'beforeClose', 'afterClose', 'onError'
-  //
-  // detail.data per platform:
-  //
-  // | Event          | Android                        | iOS                                          |
-  // |----------------|--------------------------------|----------------------------------------------|
-  // | beforeDisplay  | { id }                         | {} (empty)                                   |
-  // | onDisplay      | { id }                         | {} (empty)                                   |
-  // | beforeClose    | { id, closeAction }            | { closeAction, action }                      |
-  // | afterClose     | { id, closeAction }            | { closeAction, action }                      |
-  // | onError        | { id, errorMessage }           | { errorMessage }                             |
-  //
-  // closeAction values:
-  //   Android: string from native SDK (e.g. via InAppCloseData.getCloseAction())
-  //   iOS:     "closeButtonClicked", "buttonClicked", "openUrlClicked", or "unknown"
-  //
-  // action (iOS only): { isCloseButtonClicked, isButtonClicked, isOpenUrlClicked }
-}
-
-RetenoPlugin.setOnInAppLifecycleCallback(onInAppStatus);
-
-// Later, to unsubscribe:
-RetenoPlugin.setOnInAppLifecycleCallback(null);
-```
-
-### setOnInAppMessageCustomDataReceivedListener example
-
-Subscribe to in-app message custom data events when a button is clicked.
-
-Important: once you register this receiver, Reteno SDK will not open button links automatically. Instead, it will pass all custom data to your listener, including the link under the `url` key. You are responsible for handling navigation.
-
-```js
-RetenoPlugin.setOnInAppMessageCustomDataReceivedListener(function (event) {
-  // event.detail contains the custom data payload
-  // If a link was assigned to the button, it will be under event.detail.url
-  console.log('In-app custom data:', event.detail);
-});
-```
-
-### setDeviceToken example
-
-If you obtain a token outside this plugin (for example via another plugin/SDK), you can forward it to Reteno so it can register the device for push.
-
-Notes:
-
-- On Android, if Reteno receives FCM callbacks directly, you generally don't need to call `setDeviceToken`.
-- On iOS with Firebase, prefer the default `IOS_DEVICE_TOKEN_HANDLING_MODE=manual` flow with automatic forwarding in `init()`, described in [iOS docs](./ios.md#using-fcm-firebase-cloud-messaging-on-ios).
-
-```js
-// 1) Initialize Reteno first.
-RetenoPlugin.init()
-  .then(() => {
-    // Forward token from your token source (replace this with your integration).
-    getFcmTokenFromSomewhere(
-      (token) => {
-        if (token) RetenoPlugin.setDeviceToken(token);
-      },
-      (err) => console.error('getFcmTokenFromSomewhere: ERROR', err)
-    );
-  })
-  .catch((err) => console.error('RetenoPlugin.init: ERROR', err));
-```
-
-### setOnRetenoPushReceivedListener example
-
-Subscribe to push received events while the app is running.
-
-Notes:
-
-- On Android this is based on the SDK 2.9.6 `EventListener` / `Procedure` API (`RetenoNotifications.getReceived()`).
-- This listener is not a replacement for `getInitialNotification()` (cold start): if the app was launched by tapping a notification, use `getInitialNotification()`.
-
-```js
-// Subscribe to push received events
-function onPushReceived(event) {
-  // `event` contains the payload fields from intent extras.
-  // The exact keys depend on what Reteno/FCM delivered.
-  console.log('reteno-push-received:', event);
-}
-
-RetenoPlugin.setOnRetenoPushReceivedListener(onPushReceived);
-
-// Later, to unsubscribe:
-RetenoPlugin.removeOnRetenoPushReceivedListener(onPushReceived);
-```
-
-### setOnRetenoNotificationClickedListener example
-
-Subscribe to notification click events while the app is running.
-
-```js
-// Subscribe to notification click events
-function onNotificationClicked(event) {
-  console.log('reteno-notification-clicked:', event);
-}
-
-RetenoPlugin.setOnRetenoNotificationClickedListener(onNotificationClicked);
-
-// Later, to unsubscribe:
-RetenoPlugin.removeOnRetenoNotificationClickedListener(onNotificationClicked);
-```
-
-### setOnRetenoPushButtonClickedListener example
-
-Subscribe to push notification action button click events. When a user long-presses a push notification and taps one of the action buttons, this listener fires with `actionId`, `link`, `customData`, and `userInfo`.
-
-- **iOS**: supports up to 4 buttons per notification. You must enable the native handler via `setNotificationActionHandler({ emitEvent: true })` (or the explicit `{ enabled: true, emitEvent: true }`).
-- **Android**: supports up to 3 buttons per notification. Action button clicks are automatically detected from the notification-clicked bundle — `setNotificationActionHandler` is a no-op on Android.
-
-Payload type: `RetenoPushButtonClickedPayload` in [types](../types/index.ts).
-
-```js
-// 1. Enable notification action handler with event emission (enabled defaults to true)
-RetenoPlugin.setNotificationActionHandler({ emitEvent: true })
-  .then(() => console.log('setNotificationActionHandler: enabled'))
-  .catch((err) => console.error('setNotificationActionHandler: ERROR', err));
-
-// 2. Subscribe to action button click events
-function onPushButtonClicked(event) {
-  var detail = event && event.detail !== undefined ? event.detail : event;
-  console.log('reteno-push-button-clicked:', detail);
-  // detail.actionId - the unique button identifier
-  // detail.link - URL/deeplink associated with the button
-  // detail.customData - additional data from the button (object or raw string on Android)
-  // detail.userInfo - original notification payload
-}
-
-RetenoPlugin.setOnRetenoPushButtonClickedListener(onPushButtonClicked);
-
-// Later, to unsubscribe:
-RetenoPlugin.removeOnRetenoPushButtonClickedListener(onPushButtonClicked);
-
-// To disable the handler entirely:
-RetenoPlugin.setNotificationActionHandler(false);
-```
-
-### updateDefaultNotificationChannel example
-
-Updates the default notification channel parameters for existing users on Android devices. This is useful when you need to change how notifications appear to users who already have the app installed.
-
-Payload type: `NotificationChannelConfig` in [types](../types/index.ts).
-
-```js
-RetenoPlugin.updateDefaultNotificationChannel({
-  name: 'New Channel Name',
-  description: 'New Channel Description',
-})
-  .then(() => console.log('updateDefaultNotificationChannel: OK'))
-  .catch((err) => console.error('updateDefaultNotificationChannel: ERROR', err));
-```
-
-### setNotificationGroupingRule example
-
-Configures Android notification grouping without a JavaScript callback, so the rule also works when the WebView is not running. Payload type: `NotificationGroupingRule` in [types](../types/index.ts).
-
-```js
-// Use the value of `chatId` from each push payload as its Android group key.
-await RetenoPlugin.setNotificationGroupingRule({ payloadKey: 'chatId' });
-
-// Or put every Reteno notification into one constant group.
-await RetenoPlugin.setNotificationGroupingRule({ groupId: 'messages' });
-
-// Disable grouping.
-await RetenoPlugin.setNotificationGroupingRule(null);
-```
-
-The SDK assigns `NotificationCompat.Builder.setGroup(...)`; displaying a group-summary notification remains the application's responsibility.
-
-### getAppInboxMessages example
-
-Fetches paginated App Inbox messages. Payload type: `GetAppInboxMessagesPayload` in [types](../types/index.ts).
-
-Returns `AppInboxMessages`: `{ messages: AppInboxMessage[], totalPages: number }`.
-
-```js
-RetenoPlugin.getAppInboxMessages({
-  page: 1,
-  pageSize: 20,
-  status: 'UNOPENED', // optional: 'OPENED' | 'UNOPENED'
-})
-  .then((result) => {
-    // result.messages — array of AppInboxMessage objects
-    // result.totalPages — total number of pages
-    console.log(
-      'getAppInboxMessages: OK',
-      result.messages.length,
-      'of',
-      result.totalPages,
-      'pages'
-    );
-  })
-  .catch((err) => console.error('getAppInboxMessages: ERROR', err));
-```
-
-### getAppInboxMessagesCount example
-
-Fetches count of App Inbox messages. Returns a `number`.
-
-```js
-RetenoPlugin.getAppInboxMessagesCount()
-  .then((count) => console.log('Unread messages:', count))
-  .catch((err) => console.error('getAppInboxMessagesCount: ERROR', err));
-```
-
-### subscribeOnMessagesCountChanged example
-
-Subscribes to App Inbox messages count changes.
-
-```js
-function onInboxCountChanged(count) {
-  console.log('App Inbox count changed:', count);
-}
-
-RetenoPlugin.subscribeOnMessagesCountChanged(onInboxCountChanged, (err) => {
-  console.error('subscribeOnMessagesCountChanged: ERROR', err);
-});
-```
-
-### unsubscribeMessagesCountChanged example
-
-Unsubscribes from App Inbox messages count changes.
-
-```js
-RetenoPlugin.unsubscribeMessagesCountChanged()
-  .then(() => console.log('unsubscribeMessagesCountChanged: OK'))
-  .catch((err) => console.error('unsubscribeMessagesCountChanged: ERROR', err));
-```
-
-### markAsOpened example
-
-Marks an App Inbox message as opened.
-
-```js
-RetenoPlugin.markAsOpened('message-id')
-  .then(() => console.log('markAsOpened: OK'))
-  .catch((err) => console.error('markAsOpened: ERROR', err));
-```
-
-### markAllMessagesAsOpened example
-
-Marks all App Inbox messages as opened.
-
-```js
-RetenoPlugin.markAllMessagesAsOpened()
-  .then(() => console.log('markAllMessagesAsOpened: OK'))
-  .catch((err) => console.error('markAllMessagesAsOpened: ERROR', err));
-```
-
-### getRecommendations example
-
-Fetches recommendations. Payload type: `GetRecommendationsPayload` in [types](../types/index.ts).
-
-Returns `RecommendationsResponse`: `{ recoms: RecommendationItem[] }`. Each item contains `productId` plus the fields you requested.
-
-```js
-// Product-based recommendations.
-RetenoPlugin.getRecommendations({
-  recomVariantId: 'variant-id',
-  productIds: ['product-1', 'product-2'],
-  fields: ['name', 'price', 'image', 'link'],
-})
-  .then((result) => {
-    // result.recoms — array of recommendation items
-    // each item has productId + requested fields (name, price, etc.)
-    result.recoms.forEach((item) => console.log(item.productId, item.name));
-  })
-  .catch((err) => console.error('getRecommendations: ERROR', err));
-```
-
-```js
-// Category-based recommendations.
-RetenoPlugin.getRecommendations({
-  recomVariantId: 'variant-id',
-  categoryId: 'category-1',
-  fields: ['name', 'price'],
-})
-  .then((result) => console.log('getRecommendations: OK', result))
-  .catch((err) => console.error('getRecommendations: ERROR', err));
-```
-
-```js
-// With filters.
-RetenoPlugin.getRecommendations({
-  recomVariantId: 'variant-id',
-  productIds: ['product-1'],
-  fields: ['name', 'price'],
-  filters: [{ name: 'category', values: ['shoes', 'boots'] }],
-})
-  .then((result) => console.log('getRecommendations: OK', result))
-  .catch((err) => console.error('getRecommendations: ERROR', err));
-```
-
-### logRecommendations example
-
-Sends recommendation events. Payload type: `LogRecommendationsPayload` in [types](../types/index.ts).
-
-```js
-RetenoPlugin.logRecommendations({
-  recomVariantId: 'variant-id',
-  recomEvents: [
-    {
-      recomEventType: 'IMPRESSIONS',
-      occurred: new Date().toISOString(),
-      productId: 'product-1',
-    },
-    {
-      recomEventType: 'CLICKS',
-      occurred: new Date().toISOString(),
-      productId: 'product-2',
-    },
-  ],
-})
-  .then(() => console.log('logRecommendations: OK'))
-  .catch((err) => console.error('logRecommendations: ERROR', err));
-```