cordova-plugin-reteno 2.2.0 → 2.2.2

package/docs/Cordova/SetupGuide/Android.md

@@ -0,0 +1,135 @@
+# Android
+
+### Getting started with Reteno Plugin for Android
+
+## Installation
+
+> Requirement: `cordova-android >= 12.0.0`. Older Cordova Android platforms will refuse to install the plugin.
+
+1. Install plugin from the project root:
+
+```sh
+cordova plugin add cordova-plugin-reteno --variable RETENO_ACCESS_KEY=YOUR_KEY
+```
+
+### Configure via config.xml (Cordova)
+
+If you prefer to keep the access key in your Cordova app config (instead of passing `--variable` during installation), configure plugin variables in `config.xml`:
+
+```xml
+<widget ...>
+  <plugin name="cordova-plugin-reteno" spec="cordova-plugin-reteno">
+    <variable name="RETENO_ACCESS_KEY" value="YOUR_KEY" />
+  </plugin>
+</widget>
+```
+
+Notes:
+
+- Access-key precedence: `RETENO_ACCESS_KEY` -> deprecated `SDK_ACCESS_KEY` -> AndroidManifest meta-data injected by the plugin. New integrations should use `RETENO_ACCESS_KEY`.
+- If you changed plugin variables, usually you need reinstall/re-add:
+  - `cordova plugin rm cordova-plugin-reteno && cordova plugin add ...`
+  - or `cordova platform rm android && cordova platform add android`
+
+2. Reteno Android dependency is added automatically by the plugin Gradle hook.
+
+3. Android 13+ (`targetSdkVersion >= 33`) requires runtime permission for notifications.
+The plugin injects `POST_NOTIFICATIONS` into manifest, but you still must request it in runtime:
+
+```js
+RetenoPlugin
+  .requestNotificationPermission()
+  .then((grantedInt) => {
+    // 1 - granted, 0 - declined
+  })
+  .catch((err) => {
+    console.error(err);
+  });
+```
+
+4. Initialize SDK once on app startup.
+
+   For the full `init(...)` reference (options, platform matrix, `deviceready` wrapper) see [Initialize the SDK](./README.md#initialize-the-sdk).
+
+   > **Note**: in Cordova apps the UI runs inside a single WebView, so native automatic screen tracking is usually not meaningful. For screen analytics use `RetenoPlugin.logScreenView('ScreenName')` manually.
+
+5. Set up Firebase Cloud Messaging (FCM):
+
+- Download `google-services.json` from Firebase console.
+- Place it to your Cordova project root or `resources/android/`.
+
+![](https://raw.githubusercontent.com/reteno-com/reteno-mobile-documentation/main/Cordova/SetupGuide/Resources/google-services-json.png)
+
+- Copy your Firebase key and finish Reteno panel setup.
+
+![](https://raw.githubusercontent.com/reteno-com/reteno-mobile-documentation/main/Cordova/SetupGuide/Resources/FirebaseConsole.png)
+
+![](https://raw.githubusercontent.com/reteno-com/reteno-mobile-documentation/main/Cordova/SetupGuide/Resources/CloudConsole1.png)
+
+![](https://raw.githubusercontent.com/reteno-com/reteno-mobile-documentation/main/Cordova/SetupGuide/Resources/CloudConsole2.png)
+
+Follow official guides:
+
+- [Setting up Firebase for FCM](https://docs.reteno.com/reference/setting-up-your-firebase-application-for-firebase-cloud-messaging)
+- [Connect your mobile app in Reteno](https://docs.reteno.com/docs/connect-your-mobile-app)
+
+## Push notification listeners
+
+The plugin provides listener-based API for Android push events.
+
+- `setOnRetenoPushDismissedListener(listener)` for dismissed (swiped) pushes.
+- `setOnRetenoCustomPushReceivedListener(listener)` for custom push payloads.
+
+```js
+const onDismissed = (payload) => {
+  console.log('Push dismissed', payload);
+};
+
+const onCustomReceived = (payload) => {
+  console.log('Custom push received', payload);
+};
+
+RetenoPlugin.setOnRetenoPushDismissedListener(onDismissed);
+RetenoPlugin.setOnRetenoCustomPushReceivedListener(onCustomReceived);
+
+// later:
+RetenoPlugin.removeOnRetenoPushDismissedListener(onDismissed);
+RetenoPlugin.removeOnRetenoCustomPushReceivedListener(onCustomReceived);
+```
+
+### Without Firebasex (Cordova)
+
+If you do not need `cordova-plugin-firebasex` features, you can still use Reteno Push on Android.
+For FCM to work, your Cordova Android project must have:
+
+1. `google-services.json` from Firebase Console.
+2. Google Services Gradle plugin (`com.google.gms.google-services`) applied.
+
+How to verify:
+
+- `platforms/android/app/google-services.json` exists.
+- `platforms/android/app/build.gradle` contains `com.google.gms.google-services`.
+- Build logs do not contain `google-services.json not found`.
+
+### Warning: Reteno + Firebasex (Android)
+
+If your app also uses `cordova-plugin-firebasex`, be aware that Firebasex may register its own `FirebaseMessagingService`.
+On Android, only one service receives `com.google.firebase.MESSAGING_EVENT`, so Firebasex can prevent Reteno callbacks.
+
+Recommendation: do not install Firebasex only for push delivery if Reteno handles push in your app.
+
+## Custom FCM service (optional)
+
+Most Cordova apps do not need a custom `FirebaseMessagingService`.
+If you add one for your own native logic, extend `RetenoFirebaseMessagingService` (not `FirebaseMessagingService`) and call `super` methods.
+
+Official references:
+
+- https://docs.reteno.com/reference/android-sdk-setup
+- https://docs.reteno.com/reference/android-push-handling
+
+## Deeplinks in push payloads
+
+Reteno push notifications can include deeplinks. In Cordova apps, routing to a specific WebView route usually requires an app-level deeplink solution (custom URL scheme, App Links, or a provider such as Branch).
+
+In practice, Reteno delivers the link in payload, but opening the exact destination screen should be handled by your app deeplink layer.

package/docs/Cordova/SetupGuide/IOS.md

@@ -0,0 +1,325 @@
+# Cordova iOS SDK Setup
+
+Official guide: https://docs.reteno.com/reference/ios
+
+## Minimum SDK Requirements
+
+- iOS 15.0+
+- Xcode 15.0+
+- Swift 5.7+
+
+## Add plugin and configure preferences
+
+In `config.xml` add (or verify):
+
+```xml
+<!-- Required: Reteno iOS SDK supports iOS 15.0+ -->
+<preference name="deployment-target" value="15.0" />
+
+<!-- Reteno SDK access key (required) -->
+<preference name="RETENO_ACCESS_KEY" value="YOUR_RETENO_ACCESS_KEY" />
+```
+
+`RETENO_ACCESS_KEY` is the preferred name. The deprecated `SDK_ACCESS_KEY` preference remains supported for backward compatibility.
+
+Install plugin:
+
+```sh
+cordova plugin add cordova-plugin-reteno --variable RETENO_ACCESS_KEY=YOUR_KEY
+```
+
+If `pod install` fails with `required a higher minimum deployment target`, raise deployment target to `15.0`+.
+
+If `pod install` fails with `CocoaPods could not find compatible versions for pod "Reteno"`, your local spec repo is out of date. Run:
+
+```sh
+pod install --repo-update
+```
+
+from the `platforms/ios` directory (or pass `-- --repo-update` to `cordova build ios`).
+
+## Add Notification Service Extension (NSE)
+
+NSE is required for rich push and correct push payload handling.
+
+1. In Xcode select `File > New > Target...`
+2. Select `Notification Service Extension`.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/reteno-com/reteno-mobile-documentation/main/Cordova/SetupGuide/Resources/create_notification_service_extension.png" width="50%"/>
+</p>
+
+3. Use product name `NotificationServiceExtension`, press `Finish`.
+4. On activate scheme popup, press `Cancel`.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/reteno-com/reteno-mobile-documentation/main/Cordova/SetupGuide/Resources/choose_options_for_extension.png" width="50%"/>
+</p>
+
+5. Check extension deployment target equals main app target.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/reteno-com/reteno-mobile-documentation/main/Cordova/SetupGuide/Resources/configure_target.png" width="50%"/>
+</p>
+
+6. Replace `NotificationService.swift` contents with:
+
+```swift
+import UserNotifications
+import Reteno
+
+class NotificationService: RetenoNotificationServiceExtension {}
+```
+
+## Add App Groups
+
+Enable App Groups in both main target and `NotificationServiceExtension`.
+
+1. Main target -> `Signing & Capabilities` -> `+ Capability` -> `App Groups`
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/reteno-com/reteno-mobile-documentation/main/Cordova/SetupGuide/Resources/add_group_main_target.png" width="50%"/>
+</p>
+
+2. Add group in format:
+
+`group.{bundle_id}.reteno-local-storage`
+
+Example: `group.com.example.app.reteno-local-storage`
+
+3. Repeat in extension target.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/reteno-com/reteno-mobile-documentation/main/Cordova/SetupGuide/Resources/add_group_in_extension.png" width="50%"/>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/reteno-com/reteno-mobile-documentation/main/Cordova/SetupGuide/Resources/app_groups_capability.png" width="50%"/>
+</p>
+
+## Podfile for extension targets
+
+Plugin wires `Reteno` pod into the main iOS target automatically.
+For extension targets, add pods manually in `platforms/ios/Podfile` inside the main target block:
+
+```ruby
+target 'App' do
+  # ... existing pods ...
+
+  target 'NotificationServiceExtension' do
+    inherit! :search_paths
+    pod 'Reteno', '2.7.6'
+  end
+
+  target 'NotificationContentExtension' do
+    inherit! :search_paths
+    pod 'Reteno', '2.7.6'
+  end
+end
+```
+
+## Optional: Notification Content Extension (Images Carousel)
+
+The Notification Content Extension is required for rich push notifications with an **Images Carousel**.
+It provides the `UNNotificationContentExtension` entry point that renders a custom carousel UI.
+
+Official guide: https://docs.reteno.com/reference/ios-images-carousel
+
+### Create the extension target
+
+In Xcode: **File → New → Target → Notification Content Extension**. Name it `NotificationContentExtension`.
+
+### Replace extension files
+
+1. **Delete** the generated `MainInterface.storyboard` (it is not used with `RetenoCarouselNotificationViewController`).
+2. Replace the contents of `NotificationViewController.swift` with:
+
+```swift
+import Reteno
+
+final class NotificationViewController: RetenoCarouselNotificationViewController {}
+```
+
+### Update `Info.plist` of the NCE
+
+Open `NotificationContentExtension/Info.plist` as source code and replace the `NSExtension` dict with:
+
+```xml
+<key>NSExtension</key>
+<dict>
+    <key>NSExtensionAttributes</key>
+    <dict>
+        <key>UNNotificationExtensionCategory</key>
+        <string>ImageCarousel</string>
+        <key>UNNotificationExtensionInitialContentSizeRatio</key>
+        <real>0.5</real>
+        <key>UNNotificationExtensionUserInteractionEnabled</key>
+        <true/>
+    </dict>
+    <key>NSExtensionPointIdentifier</key>
+    <string>com.apple.usernotifications.content-extension</string>
+    <key>NSExtensionPrincipalClass</key>
+    <string>$(PRODUCT_MODULE_NAME).NotificationViewController</string>
+</dict>
+```
+
+### Deployment target
+
+Make sure the NCE **Deployment Target** in Xcode matches the main app target (iOS 15.0+). A mismatch is the most common reason carousel images fail to display.
+
+### Embed App Extensions — Copy only when installing
+
+> **This step must be done manually in Xcode.**
+
+In Xcode: **Main target → Build Phases → Embed App Extensions**. For **both** `NotificationServiceExtension` and `NotificationContentExtension` ensure **"Copy only when installing"** is **unchecked**.
+
+If this checkbox is left on, the extensions will not be embedded during Debug builds and carousel images will not appear.
+
+## Initialize the SDK in JS
+
+For the full `init(...)` reference (options, platform matrix, `deviceready` wrapper) see [Initialize the SDK](./README.md#initialize-the-sdk).
+
+## Request Notification Permission
+
+```js
+await RetenoPlugin.requestNotificationPermission();
+```
+
+## Provide Device Tokens to the SDK
+
+If another SDK/plugin obtains APNs/FCM token, forward it to Reteno:
+
+```js
+await RetenoPlugin.setDeviceToken(token);
+```
+
+## Using FCM (Firebase Cloud Messaging) on iOS
+
+If your app uses Firebase for push delivery on iOS, follow the steps below to integrate FCM token handling with Reteno.
+
+### 1. `FirebaseMessaging` pod
+
+The plugin includes `FirebaseMessaging` pod automatically via `plugin.xml`. No manual Podfile changes are needed.
+
+Whether Firebase is actually **used** for token handling depends on the `IOS_DEVICE_TOKEN_HANDLING_MODE` preference (see step 4 below).
+
+### 2. Add `GoogleService-Info.plist`
+
+Download `GoogleService-Info.plist` from the [Firebase Console](https://console.firebase.google.com/) and add it to your **iOS app target** in Xcode:
+
+- Open `platforms/ios/<AppName>.xcworkspace` in Xcode.
+- Drag `GoogleService-Info.plist` into the project navigator under the main app target.
+- Make sure **"Copy items if needed"** is checked and the file is added to the **main app target** (not only the extension targets).
+
+If your app calls `FirebaseApp.configure()` without this file, Firebase will crash at runtime. The plugin avoids auto-configuring Firebase when the file is missing and logs a warning in manual mode.
+
+### 3. Configure AppDelegate
+
+Nothing to do. Firebase iOS SDK uses **method swizzling** by default — it automatically intercepts `didRegisterForRemoteNotificationsWithDeviceToken` and forwards the APNS token to Firebase without any AppDelegate code.
+
+### 4. `IOS_DEVICE_TOKEN_HANDLING_MODE` defaults to `manual`
+
+`IOS_DEVICE_TOKEN_HANDLING_MODE` now defaults to `manual` in the plugin, so no extra config is required for the Firebase flow in most cases.
+
+If you previously overrode it to `automatic`, switch it back to `manual` to use FCM token forwarding.
+
+Only set `automatic` when you intentionally want APNS-only token handling by the native Reteno SDK.
+
+Supported modes:
+
+- `manual` (default)
+- `automatic`
+
+Any value other than `automatic` is treated as `manual`.
+
+The mode is read from iOS preferences during `RetenoPlugin.init()`. It cannot be changed at runtime from JS after plugin start.
+
+How to change mode:
+
+- Cordova: set in `config.xml` or pass during plugin installation via `--variable IOS_DEVICE_TOKEN_HANDLING_MODE=...`
+
+Cordova `config.xml` example:
+
+```xml
+<preference name="IOS_DEVICE_TOKEN_HANDLING_MODE" value="automatic" />
+```
+
+After changing this preference, run `cordova prepare ios` and rebuild the iOS app.
+
+When `IOS_DEVICE_TOKEN_HANDLING_MODE` is `manual` **and** Firebase is configured (either already configured by the app or auto-configured because `GoogleService-Info.plist` is present), the plugin automatically:
+
+1. Subscribes to Firebase Messaging delegate token updates — every future FCM token rotation is forwarded to Reteno immediately.
+2. Tries to forward the already-cached FCM token on warm starts.
+
+## In-App Status Handler (iOS)
+
+For usage examples and payload mapping, see:
+
+- [InAppMessages/README.md](../InAppMessages/README.md)
+
+## In-Apps Pause (iOS)
+
+For pause/resume examples and pause behaviour options, see:
+
+- [InAppMessages/README.md](../InAppMessages/README.md)
+
+## App lifecycle and screen tracking note
+
+Screen view tracking options:
+
+- **Manual (recommended for Cordova)** — call `RetenoPlugin.logScreenView(screenName)` on each navigation event (for example, by subscribing to your router's navigation events). This works on both iOS and Android and tracks the actual JS screens your users see.
+
+```js
+await RetenoPlugin.logScreenView('ScreenName');
+```
+
+- **Automatic** — pass `isAutomaticScreenReportingEnabled: true` to `RetenoPlugin.init(...)`. The native iOS SDK will track `UIViewController` transitions automatically. Defaults to `false`.
+
+> **Note on automatic screen tracking in hybrid apps:** In Cordova the entire UI runs inside a single WebView, so automatic tracking only captures native controller transitions (e.g. `CDVViewController`), not your JS screen navigations. The same applies to Android, where the native SDK's `autoScreenTracking` monitors `Fragment` transitions. For meaningful screen analytics in a hybrid app, always use `logScreenView()` manually.
+
+## Custom Notification Behavior (optional)
+
+After initialization you can configure foreground/tap handling from JS:
+
+```js
+await RetenoPlugin.setWillPresentNotificationOptions({
+  options: ['badge', 'sound', 'banner'],
+  emitEvent: true,
+});
+
+await RetenoPlugin.setDidReceiveNotificationResponseHandler({
+  enabled: true,
+  emitEvent: true,
+});
+```
+
+If `emitEvent: true`, plugin emits:
+
+- `reteno-push-received`
+- `reteno-notification-clicked`
+
+### Deeplinks in push payloads
+
+Reteno push notifications on iOS can include links. In hybrid Cordova apps, opening the correct in-app route usually requires a separate app-level deeplink solution.
+
+This plugin does not expose full native iOS link-handler customization to JavaScript, so for custom routing use your app deeplink layer, for example:
+
+- Branch.io
+- custom URL scheme plugin
+- Universal Links / App Links integration
+
+In practice, Reteno delivers the link in push payload, while navigation to the exact app screen should be handled by your deeplink router.
+
+## App Lifecycle Events (iOS)
+
+When lifecycle tracking is enabled, iOS can report:
+
+- `ApplicationInstalled`
+- `ApplicationUpdated`
+- `ApplicationOpened`
+- `ApplicationBackgrounded`
+
+Related automatic events are also controlled via `lifecycleTrackingOptions`:
+
+- push subscription events (`pushSubscriptionEnabled`)
+- session events (`sessionStartEventsEnabled` / `sessionEndEventsEnabled`)

package/docs/Cordova/SetupGuide/README.md

@@ -0,0 +1,91 @@
+# Cordova Plugin Setup
+
+### The Reteno Cordova Plugin for Mobile Customer Engagement and Analytics solutions
+
+## Overview
+
+`Reteno` is a plugin for Cordova that helps mobile teams integrate Reteno into their mobile apps.
+
+##### The plugin supports:
+
+- Cordova 10.2 or later
+- iOS 15.0 or later
+- Android with `cordova-android >= 12.0.0`
+
+`cordova-plugin-reteno@2.2.2` includes Reteno Android SDK 2.10.2 and Reteno iOS SDK 2.7.6.
+
+## Getting started with Reteno Plugin / Setup guide
+
+- [iOS](./IOS.md)
+- [Android](./Android.md)
+
+## Initialize the SDK
+
+`RetenoPlugin.init(...)` must be called **after Cordova's native bridge is ready**. Call it from the `deviceready` listener.
+
+### Cordova (vanilla JS)
+
+```js
+document.addEventListener('deviceready', onDeviceReady, false);
+
+function onDeviceReady() {
+  RetenoPlugin.init({
+    isDebugMode: false,
+    pauseInAppMessages: false,
+    pausePushInAppMessages: false,                // Android only
+    inAppMessagesPauseBehaviour: 'POSTPONE_IN_APPS', // iOS only: 'SKIP_IN_APPS' | 'POSTPONE_IN_APPS'
+    isAutomaticScreenReportingEnabled: false,     // iOS only
+    lifecycleTrackingOptions: {                   // or 'ALL' / 'NONE'
+      appLifecycleEnabled: true,
+      foregroundLifecycleEnabled: false,
+      pushSubscriptionEnabled: true,
+      sessionStartEventsEnabled: true,
+      sessionEndEventsEnabled: true,
+    },
+    sessionDurationSeconds: 30 * 60,              // Android 2.9.4+, iOS 2.7.0+
+  })
+    .then(() => console.log('Reteno initialized'))
+    .catch((err) => console.error('init: ERROR', err));
+}
+```
+
+### Options reference
+
+All fields are optional.
+
+| Option | Type | iOS | Android | Notes |
+|---|---|:---:|:---:|---|
+| `accessKey` | `string` | ✅ | ✅ | Overrides `RETENO_ACCESS_KEY` (or legacy `SDK_ACCESS_KEY`) from `config.xml`. Usually not needed — see "Access key" below. |
+| `isDebugMode` | `boolean` | ✅ | ✅ | Enables near real-time event monitoring. Use only on test devices. |
+| `pauseInAppMessages` | `boolean` | ✅ | ✅ | Start the SDK with in-app messages paused. |
+| `pausePushInAppMessages` | `boolean` | — | ✅ | Android-only. Safe to pass on iOS (ignored). |
+| `inAppMessagesPauseBehaviour` | `'SKIP_IN_APPS' \| 'POSTPONE_IN_APPS'` | ✅ | — | iOS-only via `init()`. On Android use [`setInAppMessagesPauseBehaviour`](../InAppMessages/README.md) at runtime. |
+| `isAutomaticScreenReportingEnabled` | `boolean` | ✅ | — | iOS-only. Not recommended in Cordova — use `logScreenView()` manually. |
+| `lifecycleTrackingOptions` | `object \| 'ALL' \| 'NONE'` | ✅ | ✅ | See [App Lifecycle Events](../AppLifeCycleEvents/README.md). iOS: only via `init()`. |
+| `sessionDurationSeconds` | `number` | ✅ | ✅ | Optional session reset duration (Android 2.9.4+, iOS 2.7.0+). |
+
+### Access key
+
+Recommended: set `RETENO_ACCESS_KEY` in `config.xml` (or via `cordova plugin add --variable RETENO_ACCESS_KEY=...`). The plugin reads it automatically — **no need to pass `accessKey` in JS**. The deprecated `SDK_ACCESS_KEY` name remains supported for backward compatibility.
+
+Only pass `accessKey` in `init()` when you need to override the value from `config.xml` at runtime.
+
+### Calling `init()` multiple times
+
+`init()` is idempotent — the plugin caches the first successful initialization and subsequent calls resolve immediately without re-initializing the native SDK. Options passed to later calls are ignored.
+
+## Feature guides
+
+- [Tracking user information](../Tracking%20user%20information/README.md)
+- [Tracking user behaviour](../Tracking%20user%20behaviour/README.md)
+- [Push notification](../Push%20notification/README.md)
+- [In app messages](../InAppMessages/README.md)
+- [Ecommerce](../Ecommerce/README.md)
+- [Recommendations](../Recommendations/README.md)
+- [App inbox](../AppInbox/README.md)
+- [Action Buttons](../Action%20Buttons/README.md)
+- [App Lifecycle Events](../AppLifeCycleEvents/README.md)
+
+##### Licence
+
+Reteno Cordova Plugin is released under the MIT license. See [LICENSE](https://github.com/reteno-com/reteno-cordova/blob/main/LICENSE) for details.

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

@@ -0,0 +1,52 @@
+# Tracking user behaviour
+
+## Track custom events
+
+```js
+RetenoPlugin.logEvent({
+  eventName: 'EVENT_NAME',
+  date: new Date().toISOString(), // optional ISO8601
+  parameters: [
+    { name: 'Additional parameter', value: 'Additional value' },
+  ],
+})
+  .then(() => console.log('logEvent: OK'))
+  .catch((err) => console.error('logEvent: ERROR', err));
+```
+
+Parameter item type:
+
+```ts
+type CustomEventParameter = {
+  name: string;
+  value?: string;
+};
+```
+
+## Force push cached data
+
+Reteno caches events locally. Use `forcePushData` to sync immediately:
+
+```js
+RetenoPlugin.forcePushData()
+  .then(() => console.log('forcePushData: OK'))
+  .catch((err) => console.error('forcePushData: ERROR', err));
+```
+
+On iOS this uses a technical `logEvent(..., forcePush: true)` call under the hood.
+
+## Log screen view events
+
+For Cordova/WebView apps, manual screen tracking is recommended:
+
+```js
+RetenoPlugin.logScreenView('HomeScreen')
+  .then(() => console.log('logScreenView: OK'))
+  .catch((err) => console.error('logScreenView: ERROR', err));
+```
+
+## Lifecycle tracking options
+
+Lifecycle tracking configuration and examples are documented in:
+
+- [AppLifeCycleEvents/README.md](../AppLifeCycleEvents/README.md)