cordova-plugin-reteno 2.2.0 → 2.2.2

package/docs/Cordova/Tracking user information/README.md

@@ -0,0 +1,112 @@
+# Tracking user information
+
+## Set user attributes (identified user)
+
+Use `setUserAttributes` with required `externalUserId`:
+
+```js
+RetenoPlugin.setUserAttributes({
+  externalUserId: 'USER_ID',
+  user: {
+    userAttributes: {
+      email: 'john.doe@example.com',
+      phone: '+1234567890',
+      firstName: 'John',
+      lastName: 'Doe',
+      languageCode: 'en',
+      timeZone: 'Europe/Kyiv',
+      marketId: 'market_1',
+      address: {
+        region: 'Kyivska',
+        town: 'Kyiv',
+        address: 'Khreshchatyk St, 1',
+        postcode: '01001',
+      },
+      fields: [{ key: 'plan', value: 'premium' }],
+    },
+    subscriptionKeys: ['news', 'promotions'],
+    groupNamesInclude: ['beta-testers'],
+    groupNamesExclude: ['unsubscribed'],
+  },
+})
+  .then(() => console.log('setUserAttributes: OK'))
+  .catch((err) => console.error('setUserAttributes: ERROR', err));
+```
+
+## Set anonymous user attributes
+
+Use `setAnonymousUserAttributes` before user identification:
+
+```js
+RetenoPlugin.setAnonymousUserAttributes({
+  firstName: 'John',
+  lastName: 'Doe',
+  languageCode: 'en',
+  timeZone: 'Europe/Kyiv',
+  marketId: 'market_1',
+  address: {
+    region: 'Kyivska',
+    town: 'Kyiv',
+    address: 'Khreshchatyk St, 1',
+    postcode: '01001',
+  },
+  fields: [{ key: 'utm_source', value: 'google' }],
+})
+  .then(() => console.log('setAnonymousUserAttributes: OK'))
+  .catch((err) => console.error('setAnonymousUserAttributes: ERROR', err));
+```
+
+Note: anonymous attributes cannot include `phone` or `email`.
+
+## Multi-account mode
+
+Use `setMultiAccountUserAttributes` when one device should receive push for multiple accounts:
+
+```js
+RetenoPlugin.setMultiAccountUserAttributes({
+  externalUserId: 'user-123',
+  user: {
+    userAttributes: {
+      email: 'john.doe@example.com',
+      phone: '+1234567890',
+      firstName: 'John',
+      lastName: 'Doe',
+      languageCode: 'en',
+      timeZone: 'Europe/Kyiv',
+      marketId: 'market_1',
+    },
+  },
+})
+  .then(() => console.log('setMultiAccountUserAttributes: OK'))
+  .catch((err) => console.error('setMultiAccountUserAttributes: ERROR', err));
+```
+
+If you want default one-token-per-device behavior, switch back to `setUserAttributes`.
+
+## Market ID
+
+`marketId` is supported by `setUserAttributes`, `setAnonymousUserAttributes`, and
+`setMultiAccountUserAttributes` starting with `cordova-plugin-reteno@2.1.0`.
+
+- The value can contain up to 64 Latin letters, digits, hyphens (`-`), and underscores (`_`).
+- Pass an empty string to clear the existing value:
+
+```js
+RetenoPlugin.setUserAttributes({
+  externalUserId: 'USER_ID',
+  user: {
+    userAttributes: {
+      marketId: '',
+    },
+  },
+});
+```
+
+- Omit `marketId` to keep the existing value unchanged.
+- The feature requires Reteno Android SDK 2.9.5+ or Reteno iOS SDK 2.7.1+. These versions are included in `cordova-plugin-reteno@2.1.0`.
+
+## Notes
+
+- `languageCode` should follow [RFC 5646](https://www.rfc-editor.org/rfc/rfc5646.html) (`de-AT`, `en`, etc).
+- `timeZone` should be from [TZ database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) (`Europe/Kyiv`, etc).
+- API payload types are available in plugin [types](https://github.com/reteno-com/reteno-cordova/blob/main/types/index.ts).

package/docs/Ionic/Action Buttons/README.md

@@ -0,0 +1,66 @@
+# Action Buttons
+
+## Configuring Action Buttons
+
+When creating mobile push notifications, you can add action buttons.
+
+- iOS supports up to 4 buttons.
+- Android supports up to 3 buttons.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/reteno-com/reteno-mobile-documentation/main/Ionic/Action%20Buttons/Resources/action_button_setup.png" width="100%"/>
+</p>
+
+Use unique `Action ID` values for different buttons.
+
+| Parameter | Notes |
+| --- | --- |
+| Action ID | Unique button action identifier |
+| Text | Text shown on the button |
+| iOS icon path | Available on iOS 15+. Name of image from app bundle |
+| Launch URL | URL/deeplink to open |
+| Custom data | Additional JSON payload |
+
+## Handle action button click
+
+### iOS
+
+Enable handler:
+
+```ts
+await this.reteno.setNotificationActionHandler({ emitEvent: true });
+// or equivalently:
+await this.reteno.setNotificationActionHandler({ enabled: true, emitEvent: true });
+```
+
+Any other value (`false`, `null`, `true`, `{ enabled: true }` without `emitEvent`) clears the handler.
+
+Subscribe:
+
+The plugin delivers the event through `document.addEventListener('reteno-push-button-clicked', ...)`, so the listener receives a DOM `CustomEvent` whose `detail` field matches `RetenoPushButtonClickedPayload`:
+
+```ts
+const onPushButtonClicked = (event: any) => {
+  const detail = event?.detail ?? event;
+  console.log('reteno-push-button-clicked:', detail);
+  // detail.actionId   — unique button action identifier
+  // detail.link       — URL/deeplink associated with the button (may be null)
+  // detail.customData — additional JSON from the button (object, or raw string on Android)
+  // detail.userInfo   — original notification payload
+};
+
+this.reteno.setOnRetenoPushButtonClickedListener(onPushButtonClicked);
+
+// later
+this.reteno.removeOnRetenoPushButtonClickedListener(onPushButtonClicked);
+```
+
+Disable:
+
+```ts
+await this.reteno.setNotificationActionHandler(false);
+```
+
+### Android
+
+`setNotificationActionHandler(...)` is no-op on Android. Action button clicks are detected automatically.

package/docs/Ionic/AppInbox/README.md

@@ -0,0 +1,61 @@
+# App Inbox
+
+## Get App Inbox messages
+
+```ts
+const result = await this.reteno.getAppInboxMessages({
+  page: 1,
+  pageSize: 20,
+  status: 'UNOPENED', // optional: 'OPENED' | 'UNOPENED'
+});
+
+console.log(result.messages, result.totalPages);
+```
+
+Returns `AppInboxMessages`: `{ messages: AppInboxMessage[], totalPages: number }`. Each `AppInboxMessage` contains:
+
+```ts
+type AppInboxMessage = {
+  id: string;
+  title: string;
+  createdDate: string;
+  isNewMessage: boolean;
+  content?: string | null;
+  imageUrl?: string | null;
+  linkUrl?: string | null;
+  category?: string | null;
+  status?: 'OPENED' | 'UNOPENED' | null;
+  customData?: Record<string, string> | null;
+};
+```
+
+## Get unread messages count
+
+```ts
+const count = await this.reteno.getAppInboxMessagesCount();
+console.log('Unread messages:', count);
+```
+
+## Subscribe to count changes
+
+```ts
+this.reteno.subscribeOnMessagesCountChanged().subscribe({
+  next: (count) => console.log('App Inbox count changed:', count),
+  error: (err) => console.error('subscribeOnMessagesCountChanged:', err),
+});
+
+// later
+await this.reteno.unsubscribeMessagesCountChanged();
+```
+
+## Mark message as opened
+
+```ts
+await this.reteno.markAsOpened('message-id');
+```
+
+## Mark all messages as opened
+
+```ts
+await this.reteno.markAllMessagesAsOpened();
+```

package/docs/Ionic/AppLifeCycleEvents/README.md

@@ -0,0 +1,77 @@
+# App Lifecycle Events
+
+Reteno can automatically track app lifecycle, foreground lifecycle, push subscription, and session events.
+
+## Tracked app lifecycle events
+
+When `appLifecycleEnabled` is enabled:
+
+- `ApplicationInstalled`
+- `ApplicationUpdated`
+- `ApplicationOpened`
+- `ApplicationBackgrounded`
+
+## Tracked foreground lifecycle events
+
+When `foregroundLifecycleEnabled` is enabled:
+
+- `ApplicationOpened`
+- `ApplicationBackgrounded`
+
+## Tracked push subscription events
+
+When `pushSubscriptionEnabled` is enabled:
+
+- `PushNotificationsSubscribed`
+- `PushNotificationsUnsubscribed`
+
+## Tracked session events
+
+When `sessionStartEventsEnabled` / `sessionEndEventsEnabled` are enabled:
+
+- `SessionStarted`
+- `SessionEnded`
+
+## Configure lifecycle tracking
+
+During initialization:
+
+```ts
+await this.reteno.init({
+  lifecycleTrackingOptions: {
+    appLifecycleEnabled: true,
+    foregroundLifecycleEnabled: false,
+    pushSubscriptionEnabled: true,
+    sessionStartEventsEnabled: true,
+    sessionEndEventsEnabled: false,
+  },
+});
+```
+
+Shortcuts:
+
+```ts
+await this.reteno.init({ lifecycleTrackingOptions: 'ALL' });
+await this.reteno.init({ lifecycleTrackingOptions: 'NONE' });
+```
+
+Runtime update:
+
+```ts
+await this.reteno.setLifecycleTrackingOptions({
+  sessionStartEventsEnabled: true,
+  sessionEndEventsEnabled: true,
+});
+```
+
+iOS note: runtime method `setLifecycleTrackingOptions(...)` works only before `init()`.  
+Use `lifecycleTrackingOptions` in `init(...)` as the main configuration path for iOS.
+Legacy note: `sessionEventsEnabled` is still supported as an alias that toggles both session start and end events.
+
+## Screen tracking in Ionic/Cordova
+
+Use manual tracking:
+
+```ts
+await this.reteno.logScreenView('HomeScreen');
+```

package/docs/Ionic/Ecommerce/README.md

@@ -0,0 +1,139 @@
+# Ecommerce Activity Tracking
+
+Use `logEcommerceEvent(...)`.
+
+Supported `eventType` values:
+
+- `productViewed`
+- `productCategoryViewed`
+- `productAddedToWishlist`
+- `cartUpdated`
+- `orderCreated`
+- `orderUpdated`
+- `orderDelivered`
+- `orderCancelled`
+- `searchRequest`
+
+`currencyCode` should use ISO 4217 format (for example: `USD`, `EUR`, `GBP`).
+
+## Product viewed
+
+```ts
+await this.reteno.logEcommerceEvent({
+  eventType: 'productViewed',
+  product: {
+    productId: 'SKU-123',
+    price: 29.99,
+    isInStock: true,
+    attributes: [{ name: 'color', value: ['red', 'blue'] }],
+  },
+  currencyCode: 'USD',
+});
+```
+
+## Product category viewed
+
+```ts
+await this.reteno.logEcommerceEvent({
+  eventType: 'productCategoryViewed',
+  category: {
+    productCategoryId: 'CATEGORY-01',
+    attributes: [{ name: 'gender', value: ['women'] }],
+  },
+});
+```
+
+## Product added to wishlist
+
+```ts
+await this.reteno.logEcommerceEvent({
+  eventType: 'productAddedToWishlist',
+  product: {
+    productId: 'SKU-123',
+    price: 29.99,
+    isInStock: true,
+    attributes: [{ name: 'color', value: ['red'] }],
+  },
+  currencyCode: 'USD',
+});
+```
+
+## Cart updated
+
+```ts
+await this.reteno.logEcommerceEvent({
+  eventType: 'cartUpdated',
+  cartId: 'cart-456',
+  products: [
+    {
+      productId: 'SKU-123',
+      quantity: 2,
+      price: 29.99,
+      name: 'T-Shirt',
+      category: 'Apparel',
+    },
+  ],
+  currencyCode: 'USD',
+});
+```
+
+## Order created
+
+`status` accepts `'INITIALIZED' | 'IN_PROGRESS' | 'DELIVERED' | 'CANCELLED'` (plus any custom string).
+
+```ts
+await this.reteno.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',
+});
+```
+
+## Order updated
+
+```ts
+await this.reteno.logEcommerceEvent({
+  eventType: 'orderUpdated',
+  order: {
+    externalOrderId: 'ORD-789',
+    totalCost: 59.98,
+    status: 'IN_PROGRESS',
+    date: new Date().toISOString(),
+  },
+  currencyCode: 'USD',
+});
+```
+
+## Order delivered / cancelled
+
+For these event types use `externalOrderId` (not full `order` object):
+
+```ts
+await this.reteno.logEcommerceEvent({ eventType: 'orderDelivered', externalOrderId: 'ORD-789' });
+await this.reteno.logEcommerceEvent({ eventType: 'orderCancelled', externalOrderId: 'ORD-789' });
+```
+
+## Search request
+
+```ts
+await this.reteno.logEcommerceEvent({
+  eventType: 'searchRequest',
+  search: 'red t-shirt',
+  isFound: true,
+});
+```

package/docs/Ionic/InAppMessages/README.md

@@ -0,0 +1,65 @@
+# In-app messages
+
+## Pause and resume in-app messages
+
+```ts
+await this.reteno.pauseInAppMessages(true);  // pause
+await this.reteno.pauseInAppMessages(false); // resume
+```
+
+## Configure pause behaviour
+
+```ts
+await this.reteno.setInAppMessagesPauseBehaviour('SKIP_IN_APPS');
+await this.reteno.setInAppMessagesPauseBehaviour('POSTPONE_IN_APPS');
+```
+
+On iOS you can also preconfigure the pause behaviour during `init()` via `inAppMessagesPauseBehaviour` — see the options table in [Setup overview](../SetupGuide/README.md#options-reference).
+
+## Subscribe to in-app lifecycle events
+
+```ts
+const onInAppStatus = (event: any) => {
+  const detail = event?.detail ?? event;
+  console.log('In-app status:', detail?.event, detail?.data);
+};
+
+await this.reteno.setOnInAppLifecycleCallback(onInAppStatus);
+
+// unsubscribe
+await this.reteno.setOnInAppLifecycleCallback(null);
+```
+
+### Platform-specific payload (`detail.data`)
+
+| Event | Android | iOS |
+|---|---|---|
+| `beforeDisplay` | `{ id }` | `{}` |
+| `onDisplay` | `{ id }` | `{}` |
+| `beforeClose` | `{ id, closeAction }` | `{ closeAction, action }` |
+| `afterClose` | `{ id, closeAction }` | `{ closeAction, action }` |
+| `onError` | `{ id, errorMessage }` | `{ errorMessage }` |
+
+In short: Android payload usually includes in-app `id`, while iOS payload for display events is empty (`{}`) and does not include message id.
+
+`closeAction` values:
+- **Android**: string from native SDK (e.g. via `InAppCloseData.getCloseAction()`)
+- **iOS**: `"closeButtonClicked"`, `"buttonClicked"`, `"openUrlClicked"`, or `"unknown"`
+
+`action` (iOS only): `{ isCloseButtonClicked, isButtonClicked, isOpenUrlClicked }`
+
+## Receive custom data from in-app (Android)
+
+```ts
+const onCustomData = (event: any) => {
+  const detail = event?.detail ?? event;
+  console.log('In-app custom data:', detail);
+};
+
+this.reteno.setOnInAppMessageCustomDataReceivedListener(onCustomData);
+
+// later
+this.reteno.removeOnInAppMessageCustomDataReceivedListener(onCustomData);
+```
+
+Important: when this listener is registered, automatic opening of in-app button links is disabled. Handle navigation yourself (for example, using `detail.url` / `payload.url`).

package/docs/Ionic/Push notification/README.md

@@ -0,0 +1,133 @@
+# Push notification
+
+## Request notification permission
+
+```ts
+const granted = await this.reteno.requestNotificationPermission();
+console.log('Permission result:', granted);
+```
+
+## Get initial notification
+
+On Android, `getInitialNotification()` returns only a Reteno push payload
+identified by `es_interaction_id`. Intent extras from Branch or other deeplink
+SDKs are ignored. If the app was not opened from a Reteno push, the method
+returns an empty object.
+
+```ts
+const initial = await this.reteno.getInitialNotification();
+console.log('Initial push payload:', initial);
+```
+
+## Listen for received push
+
+```ts
+const onPushReceived = (event: any) => {
+  console.log('reteno-push-received', event);
+};
+
+this.reteno.setOnRetenoPushReceivedListener(onPushReceived);
+
+// later
+this.reteno.removeOnRetenoPushReceivedListener(onPushReceived);
+```
+
+## Listen for notification click
+
+```ts
+const onClicked = (event: any) => {
+  console.log('reteno-notification-clicked', event);
+};
+
+this.reteno.setOnRetenoNotificationClickedListener(onClicked);
+
+// later
+this.reteno.removeOnRetenoNotificationClickedListener(onClicked);
+```
+
+## Android-only listeners
+
+```ts
+const onDismissed = (payload: any) => console.log('Push dismissed', payload);
+const onCustomReceived = (payload: any) => console.log('Custom push received', payload);
+
+this.reteno.setOnRetenoPushDismissedListener(onDismissed);
+this.reteno.setOnRetenoCustomPushReceivedListener(onCustomReceived);
+
+// later
+this.reteno.removeOnRetenoPushDismissedListener(onDismissed);
+this.reteno.removeOnRetenoCustomPushReceivedListener(onCustomReceived);
+```
+
+## iOS foreground/tap handlers (optional)
+
+These methods are iOS-only. On Android they are not implemented and calls return an error (`Promise` reject / `error` callback).
+
+```ts
+await this.reteno.setWillPresentNotificationOptions({
+  options: ['badge', 'sound', 'banner'],
+  emitEvent: true,
+});
+
+await this.reteno.setDidReceiveNotificationResponseHandler({
+  enabled: true,
+  emitEvent: true,
+});
+```
+
+`options` accepts any combination of `NotificationPresentationOption` values: `'badge' | 'sound' | 'alert' | 'banner' | 'list'`.
+
+Shorthand forms accepted by `setWillPresentNotificationOptions`:
+
+```ts
+// Pass only the options array
+await this.reteno.setWillPresentNotificationOptions(['badge', 'sound', 'banner']);
+
+// Clear previously set options
+await this.reteno.setWillPresentNotificationOptions(null);
+```
+
+`setDidReceiveNotificationResponseHandler` also accepts `boolean | null` to disable or clear the handler:
+
+```ts
+await this.reteno.setDidReceiveNotificationResponseHandler(false);
+```
+
+If `emitEvent: true`, plugin emits JS events:
+
+- `reteno-push-received`
+- `reteno-notification-clicked`
+
+## Pass token manually
+
+```ts
+await this.reteno.setDeviceToken(token);
+```
+
+Use this when token callbacks are handled outside `cordova-plugin-reteno` (for example, by another plugin/SDK that owns APNs/FCM token delivery).
+
+## Android default channel update
+
+```ts
+await this.reteno.updateDefaultNotificationChannel({
+  name: 'New Channel Name',
+  description: 'New Channel Description',
+});
+```
+
+## Android notification grouping
+
+Groups Android notifications by a value from the push payload or by a constant group ID. The rule is persisted natively and restored when the Android process starts, so it also applies to a push handled before the WebView is active.
+
+```ts
+// Group notifications by the `chatId` field in the push payload.
+await this.reteno.setNotificationGroupingRule({ payloadKey: 'chatId', showSummary: true });
+
+// Or assign every Reteno notification to one constant group.
+await this.reteno.setNotificationGroupingRule({ groupId: 'messages', showSummary: true });
+
+// Disable grouping.
+await this.reteno.setNotificationGroupingRule(null);
+```
+
+`showSummary` is optional and defaults to `false`. When enabled, the plugin creates and maintains an Android group-summary notification for the group ("You have N new notifications") once at least two notifications share it, and removes the summary once fewer than two remain. Without `showSummary`, grouping only sets the group key on each notification — no collapsed summary row appears unless the app posts its own summary notification.

package/docs/Ionic/Recommendations/README.md

@@ -0,0 +1,46 @@
+# Recommendations
+
+## Get recommendations
+
+```ts
+const result = await this.reteno.getRecommendations({
+  recomVariantId: 'variant-id',
+  productIds: ['product-1', 'product-2'],
+  fields: ['name', 'price', 'image', 'link'],
+});
+
+console.log(result.recoms);
+```
+
+Category-based:
+
+```ts
+await this.reteno.getRecommendations({
+  recomVariantId: 'variant-id',
+  categoryId: 'category-1',
+  fields: ['name', 'price'],
+});
+```
+
+With filters (accepts a single filter object or an array):
+
+```ts
+await this.reteno.getRecommendations({
+  recomVariantId: 'variant-id',
+  productIds: ['product-1'],
+  fields: ['name', 'price'],
+  filters: [{ name: 'category', values: ['shoes', 'boots'] }],
+});
+```
+
+## Log recommendation events
+
+```ts
+await this.reteno.logRecommendations({
+  recomVariantId: 'variant-id',
+  recomEvents: [
+    { recomEventType: 'IMPRESSIONS', occurred: new Date().toISOString(), productId: 'product-1' },
+    { recomEventType: 'CLICKS', occurred: new Date().toISOString(), productId: 'product-2' },
+  ],
+});
+```