cordova-plugin-reteno 2.1.0 → 2.2.1

package/README.md

@@ -2,6 +2,8 @@
 
 Reteno SDK for Cordova and Capacitor apps.
 
+Version 2.2.1 includes Reteno Android SDK 2.10.2 and Reteno iOS SDK 2.7.4.
+
 ## Installation
 
 ```bash
@@ -10,6 +12,8 @@ npm install cordova-plugin-reteno
 
 ## Documentation
 
+- [Bundled Cordova documentation](docs/Cordova/SetupGuide/README.md)
+- [Bundled Ionic documentation](docs/Ionic/SetupGuide/README.md)
 - [Cordova SDK Overview](https://docs.reteno.com/reference/cordova-sdk-setup)
 - [Ionic SDK Overview](https://docs.reteno.com/reference/ionic-sdk)
 

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

@@ -0,0 +1,62 @@
+# Action Buttons
+
+## Configuring Action Buttons
+
+When creating mobile push notifications, you can add action buttons.
+
+- iOS supports up to 4 buttons in one notification.
+- Android supports up to 3 buttons in one notification.
+
+### Adding Action Buttons
+
+1. In Reteno, open `Messages -> Mobile Push`.
+2. Create a push or edit existing one.
+3. Configure the `Buttons` section.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/reteno-com/reteno-mobile-documentation/main/Cordova/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
+
+Enable handler for iOS event emission:
+
+```js
+await RetenoPlugin.setNotificationActionHandler({ emitEvent: true });
+```
+
+Subscribe:
+
+```js
+function onPushButtonClicked(event) {
+  const detail = event && event.detail !== undefined ? event.detail : event;
+  console.log('reteno-push-button-clicked:', detail);
+  // detail.actionId
+  // detail.link
+  // detail.customData
+  // detail.userInfo
+}
+
+RetenoPlugin.setOnRetenoPushButtonClickedListener(onPushButtonClicked);
+
+// later
+RetenoPlugin.removeOnRetenoPushButtonClickedListener(onPushButtonClicked);
+```
+
+Disable handler:
+
+```js
+await RetenoPlugin.setNotificationActionHandler(false);
+```
+
+Android note: `setNotificationActionHandler(...)` is no-op on Android. Action button clicks are detected automatically.

package/docs/Cordova/AppInbox/README.md

@@ -0,0 +1,55 @@
+# App inbox
+
+## Get App Inbox messages
+
+```js
+RetenoPlugin.getAppInboxMessages({
+  page: 1,
+  pageSize: 20,
+  status: 'UNOPENED', // optional: OPENED | UNOPENED
+})
+  .then((result) => {
+    console.log('messages:', result.messages);
+    console.log('totalPages:', result.totalPages);
+  })
+  .catch((err) => console.error('getAppInboxMessages: ERROR', err));
+```
+
+## Get unread messages count
+
+```js
+RetenoPlugin.getAppInboxMessagesCount()
+  .then((count) => console.log('Unread messages:', count))
+  .catch((err) => console.error('getAppInboxMessagesCount: ERROR', err));
+```
+
+## Subscribe to count changes
+
+```js
+function onInboxCountChanged(count) {
+  console.log('App Inbox count changed:', count);
+}
+
+RetenoPlugin.subscribeOnMessagesCountChanged(onInboxCountChanged, (err) => {
+  console.error('subscribeOnMessagesCountChanged: ERROR', err);
+});
+
+// unsubscribe
+RetenoPlugin.unsubscribeMessagesCountChanged();
+```
+
+## Mark message as opened
+
+```js
+RetenoPlugin.markAsOpened('message-id')
+  .then(() => console.log('markAsOpened: OK'))
+  .catch((err) => console.error('markAsOpened: ERROR', err));
+```
+
+## Mark all messages as opened
+
+```js
+RetenoPlugin.markAllMessagesAsOpened()
+  .then(() => console.log('markAllMessagesAsOpened: OK'))
+  .catch((err) => console.error('markAllMessagesAsOpened: ERROR', err));
+```

package/docs/Cordova/AppLifeCycleEvents/README.md

@@ -0,0 +1,80 @@
+# 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
+
+Configure during initialization:
+
+```js
+RetenoPlugin.init({
+  lifecycleTrackingOptions: {
+    appLifecycleEnabled: true,
+    foregroundLifecycleEnabled: false,
+    pushSubscriptionEnabled: true,
+    sessionStartEventsEnabled: true,
+    sessionEndEventsEnabled: false,
+  },
+});
+```
+
+Or with shortcuts:
+
+```js
+RetenoPlugin.init({ lifecycleTrackingOptions: 'ALL' });
+RetenoPlugin.init({ lifecycleTrackingOptions: 'NONE' });
+```
+
+You can also call:
+
+```js
+RetenoPlugin.setLifecycleTrackingOptions({
+  sessionStartEventsEnabled: true,
+  sessionEndEventsEnabled: true,
+});
+RetenoPlugin.setLifecycleTrackingOptions('ALL');
+RetenoPlugin.setLifecycleTrackingOptions('NONE');
+```
+
+iOS note: `setLifecycleTrackingOptions(...)` must be called before `init()`.
+Legacy note: `sessionEventsEnabled` is still supported as an alias that toggles both session start and end events.
+
+## Screen tracking in Cordova
+
+For Cordova apps, manual screen tracking is recommended:
+
+```js
+RetenoPlugin.logScreenView('HomeScreen');
+```
+
+Automatic native screen tracking in hybrid WebView apps does not reflect JS route changes.

package/docs/Cordova/Ecommerce/README.md

@@ -0,0 +1,144 @@
+# Ecommerce Activity Tracking
+
+Reteno tracks ecommerce activity using `logEcommerceEvent(...)`.
+
+Supported `eventType` values:
+
+- `productViewed`
+- `productCategoryViewed`
+- `productAddedToWishlist`
+- `cartUpdated`
+- `orderCreated`
+- `orderUpdated`
+- `orderDelivered`
+- `orderCancelled`
+- `searchRequest`
+
+## Product viewed
+
+```js
+RetenoPlugin.logEcommerceEvent({
+  eventType: 'productViewed',
+  product: {
+    productId: 'SKU-123',
+    price: 29.99,
+    isInStock: true,
+    attributes: [{ name: 'color', value: ['red', 'blue'] }],
+  },
+  currencyCode: 'USD',
+});
+```
+
+## Product category viewed
+
+```js
+RetenoPlugin.logEcommerceEvent({
+  eventType: 'productCategoryViewed',
+  category: {
+    productCategoryId: 'CATEGORY-01',
+    attributes: [{ name: 'gender', value: ['women'] }],
+  },
+});
+```
+
+## Product added to wishlist
+
+```js
+RetenoPlugin.logEcommerceEvent({
+  eventType: 'productAddedToWishlist',
+  product: {
+    productId: 'SKU-123',
+    price: 29.99,
+    isInStock: true,
+    attributes: [{ name: 'color', value: ['red'] }],
+  },
+  currencyCode: 'USD',
+});
+```
+
+## Cart updated
+
+```js
+RetenoPlugin.logEcommerceEvent({
+  eventType: 'cartUpdated',
+  cartId: 'cart-456',
+  products: [
+    {
+      productId: 'SKU-123',
+      quantity: 2,
+      price: 29.99,
+      name: 'T-Shirt',
+      category: 'Apparel',
+    },
+  ],
+  currencyCode: 'USD',
+});
+```
+
+## Order created
+
+```js
+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',
+});
+```
+
+## Order updated
+
+```js
+RetenoPlugin.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 the payload requires `externalOrderId` (not full `order` object):
+
+```js
+RetenoPlugin.logEcommerceEvent({
+  eventType: 'orderDelivered',
+  externalOrderId: 'ORD-789',
+});
+
+RetenoPlugin.logEcommerceEvent({
+  eventType: 'orderCancelled',
+  externalOrderId: 'ORD-789',
+});
+```
+
+## Search request
+
+```js
+RetenoPlugin.logEcommerceEvent({
+  eventType: 'searchRequest',
+  search: 'red t-shirt',
+  isFound: true,
+});
+```
+
+Use valid [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217) currency codes.

package/docs/Cordova/InAppMessages/README.md

@@ -0,0 +1,72 @@
+# In app messages
+
+## Pause and resume In-App messages
+
+```js
+// pause
+RetenoPlugin.pauseInAppMessages(true)
+  .then(() => console.log('In-apps paused'))
+  .catch((err) => console.error(err));
+
+// resume
+RetenoPlugin.pauseInAppMessages(false)
+  .then(() => console.log('In-apps resumed'))
+  .catch((err) => console.error(err));
+```
+
+## Configure pause behaviour
+
+```js
+// Drop in-apps received while paused
+RetenoPlugin.setInAppMessagesPauseBehaviour('SKIP_IN_APPS');
+
+// Queue one and show later after resume
+RetenoPlugin.setInAppMessagesPauseBehaviour('POSTPONE_IN_APPS');
+```
+
+## Subscribe to In-App lifecycle events
+
+```js
+function onInAppStatus(event) {
+  const detail = event.detail || event;
+  console.log('In-app status:', detail.event, detail.data);
+  // detail.event:
+  // beforeDisplay, onDisplay, beforeClose, afterClose, onError
+}
+
+RetenoPlugin.setOnInAppLifecycleCallback(onInAppStatus);
+
+// unsubscribe
+RetenoPlugin.setOnInAppLifecycleCallback(null);
+```
+
+### Platform-specific payload (`detail.data`)
+
+| 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 }`
+
+## Receive custom data from In-App (Android)
+
+```js
+function onInAppCustomData(event) {
+  console.log('In-app custom data:', event.detail);
+}
+
+RetenoPlugin.setOnInAppMessageCustomDataReceivedListener(onInAppCustomData);
+
+// later
+RetenoPlugin.removeOnInAppMessageCustomDataReceivedListener(onInAppCustomData);
+```
+
+Important: when this listener is registered, automatic opening of In-App button links is disabled. Handle navigation yourself (for example, using `event.detail.url`).

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

@@ -0,0 +1,124 @@
+# Push notification
+
+## Request notification permission
+
+```js
+RetenoPlugin.requestNotificationPermission()
+  .then((result) => {
+    // Android: 1 granted / 0 declined
+    console.log('Permission result:', result);
+  })
+  .catch((err) => console.error(err));
+```
+
+## Get initial notification
+
+When app starts from push tap, get payload with `getInitialNotification()`:
+
+```js
+RetenoPlugin.getInitialNotification()
+  .then((data) => console.log('getInitialNotification', data))
+  .catch((err) => console.error('getInitialNotification: ERROR', err));
+```
+
+## Listen for received push while app is active
+
+```js
+function onPushReceived(event) {
+  console.log('reteno-push-received:', event);
+}
+
+RetenoPlugin.setOnRetenoPushReceivedListener(onPushReceived);
+
+// later
+RetenoPlugin.removeOnRetenoPushReceivedListener(onPushReceived);
+```
+
+## Listen for push click events
+
+```js
+function onNotificationClicked(event) {
+  console.log('reteno-notification-clicked:', event);
+}
+
+RetenoPlugin.setOnRetenoNotificationClickedListener(onNotificationClicked);
+
+// later
+RetenoPlugin.removeOnRetenoNotificationClickedListener(onNotificationClicked);
+```
+
+## Android-only listeners
+
+```js
+function onDismissed(payload) {
+  console.log('Push dismissed', payload);
+}
+
+function onCustomReceived(payload) {
+  console.log('Custom push received', payload);
+}
+
+RetenoPlugin.setOnRetenoPushDismissedListener(onDismissed);
+RetenoPlugin.setOnRetenoCustomPushReceivedListener(onCustomReceived);
+
+// later
+RetenoPlugin.removeOnRetenoPushDismissedListener(onDismissed);
+RetenoPlugin.removeOnRetenoCustomPushReceivedListener(onCustomReceived);
+```
+
+## iOS foreground/tap handlers (optional)
+
+These methods are **iOS-only**. On Android they are not implemented and calls will fail.
+
+```js
+await RetenoPlugin.setWillPresentNotificationOptions({
+  options: ['badge', 'sound', 'banner'],
+  emitEvent: true,
+});
+
+await RetenoPlugin.setDidReceiveNotificationResponseHandler({
+  enabled: true,
+  emitEvent: true,
+});
+```
+
+If `emitEvent: true`, plugin emits JS events:
+
+- `reteno-push-received`
+- `reteno-notification-clicked`
+
+## Pass token manually (if another plugin gets it)
+
+```js
+await RetenoPlugin.setDeviceToken(token);
+```
+
+Use this when token callbacks are handled outside `cordova-plugin-reteno`.
+
+## Android default notification channel update
+
+```js
+RetenoPlugin.updateDefaultNotificationChannel({
+  name: 'New Channel Name',
+  description: 'New Channel Description',
+})
+  .then(() => console.log('updateDefaultNotificationChannel: OK'))
+  .catch((err) => console.error('updateDefaultNotificationChannel: ERROR', err));
+```
+
+## 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.
+
+```js
+// Group notifications by the `chatId` field in the push payload.
+await RetenoPlugin.setNotificationGroupingRule({ payloadKey: 'chatId', showSummary: true });
+
+// Or assign every Reteno notification to one constant group.
+await RetenoPlugin.setNotificationGroupingRule({ groupId: 'messages', showSummary: true });
+
+// Disable grouping.
+await RetenoPlugin.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/Cordova/Recommendations/README.md

@@ -0,0 +1,62 @@
+# Recommendations
+
+## Get recommendations
+
+```js
+RetenoPlugin.getRecommendations({
+  recomVariantId: 'variant-id',
+  productIds: ['product-1', 'product-2'],
+  fields: ['name', 'price', 'image', 'link'],
+})
+  .then((result) => {
+    result.recoms.forEach((item) => {
+      console.log(item.productId, item.name);
+    });
+  })
+  .catch((err) => console.error('getRecommendations: ERROR', err));
+```
+
+Category-based example:
+
+```js
+RetenoPlugin.getRecommendations({
+  recomVariantId: 'variant-id',
+  categoryId: 'category-1',
+  fields: ['name', 'price'],
+});
+```
+
+With filters:
+
+```js
+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));
+```
+
+## Log recommendation events
+
+```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));
+```