## Purpose This runbook helps an AI coding agent integrate the Reteno Cordova SDK into an existing Cordova application and validate that the integration works correctly. You must not stop after applying code changes. The integration is complete only when the required validation checks pass or a blocker is clearly documented. ## Agent Role You are an AI coding agent responsible for integrating the Reteno Cordova SDK into an existing Cordova application. Your goal is not only to update the code, but also to validate that the SDK integration works correctly across the Cordova JavaScript layer and the required native iOS / Android platform configuration. Do not treat this as a plain native iOS, native Android, Ionic, Capacitor, React Native, Flutter, Expo, or Unity integration by default. Start with the Cordova project structure and Cordova platform setup. Apply native iOS or Android changes only when the Cordova SDK setup or selected Cordova platform requires them. ## Quick Start Prompt Use this Cordova runbook as your operating instruction. Integrate the Reteno Cordova SDK from scratch into the selected Cordova application. First inspect the project and detect the Cordova project structure, package manager, Cordova version, Cordova Android version, installed platforms, installed plugins, app entry point, existing Reteno usage, Firebase setup, FCM/APNs setup, native iOS/Android platform folders, and existing push notification logic. Use the official [Reteno Cordova SDK](https://docs.reteno.com/reference/cordova-sdk-setup) as the primary source of truth for Cordova SDK overview and base setup. Use the official [Cordova Android SDK Setup](https://docs.reteno.com/reference/cordova-android-sdk-setup) when Android validation is included. Use the official [Cordova iOS SDK Setup](https://docs.reteno.com/reference/cordova-ios-sdk-setup) when iOS validation is included. Use the official [Cordova User Information](https://docs.reteno.com/reference/cordova-user-information) when user identification or `externalCustomerId` validation is part of the current integration task. Use the official [Cordova SDK Release Notes](https://docs.reteno.com/page/cordova-sdk-release-notes) to check SDK versions, migration notes, compatibility issues, native SDK versions, and known fixes. Before applying Cordova SDK changes, explicitly verify the Cordova-specific critical setup decisions: - selected `cordova-plugin-reteno` version; - Cordova project type: - pure Cordova app; - Ionic app using Cordova runtime; - Capacitor app using Cordova plugin compatibility layer; - non-Cordova project; - whether this runbook or the Ionic runbook should be used; - Cordova CLI / supported stack version; - whether the detected Cordova version is `10.2` or later according to the current Cordova SDK documentation; - `cordova-android` version; - `cordova-ios` version, if iOS validation is included; - whether `cordova-ios` is `8.0.0` or higher when iOS validation is included; - installed platforms: - Android; - iOS; - both; - whether `platforms/` folders are committed or generated; - whether regenerating Cordova platforms is allowed; - whether running `cordova platform rm/add` is allowed; - whether running `cordova prepare` is allowed; - whether `cordova-plugin-reteno` is already installed; - whether `SDK_ACCESS_KEY` is configured through plugin variable, `config.xml`, or runtime JS init; - whether `RetenoPlugin.init(...)` is required and where it should be called; - whether `RetenoPlugin.requestNotificationPermission()` is required; - Android `cordova-android >= 12.0.0`; - Android FCM setup and `google-services.json`; - Android 13+ notification permission handling; - whether `cordova-plugin-firebasex` is installed and may conflict with Reteno FCM handling; - iOS `deployment-target` is `15.0` or higher; - iOS `IOS_DEVICE_TOKEN_HANDLING_MODE`: `manual` or `automatic`; - whether iOS push uses direct APNs or Firebase / FCM; - whether `RetenoPlugin.setDeviceToken(token)` is required; - iOS Notification Service Extension; - iOS App Group exact name; - iOS extension Podfile setup; - selected test environment. Do not treat Cordova platform folders as source of truth before confirming whether they are generated or committed source. Do not remove and re-add Cordova platforms unless the developer explicitly confirms that this is allowed. Do not mark integration as complete until these decisions are confirmed or documented as not applicable. Before making code changes, complete the [Developer Preparation Checklist](#developer-preparation-checklist). If any required preparation item is missing, document it before continuing and do not mark the integration as complete until the missing validation step is completed or clearly reported as blocked. Do not ask for all inputs upfront. Ask only for information that cannot be detected from the codebase, Reteno MCP, official Reteno documentation, or Cordova project configuration. Preserve existing application logic. Do not overwrite Cordova app startup, `deviceready` handlers, Cordova plugins, Firebase configuration, push notification handlers, deeplink handling, authentication flow, analytics logic, or existing native platform configuration. Use the existing Cordova project setup. Do not switch package managers, Cordova platforms, build system, Firebase setup, push provider, SDK versions, or native project ownership unless the developer explicitly confirms this. Before making code changes, check the current Git branch. For evaluation, test, or temporary integration runs, create and switch to a temporary local branch unless the developer explicitly confirms another branch. Do not make temporary integration changes directly on `main` or `master`. If a Reteno SDK access key is provided, use it through the approved project configuration method. Do not leave SDK key placeholders in the final code. Do not hardcode secrets, Firebase server credentials, APNs credentials, service account data, private keys, certificates, or other sensitive values in committed files. Use the selected test environment confirmed by the developer. This can be an Android emulator, physical Android device, iOS simulator, physical iOS device, local Cordova build, CI build, or another supported test environment. After applying SDK changes, attempt to build and run the application. If build/run fails, do not repeat the same failed action without a new hypothesis. Continue safe diagnostics while distinct testable causes remain. Escalate when the issue requires local environment access, external access, credentials, signing, dashboard changes, GUI interaction, local automation, Apple Developer account access, Firebase server configuration, Cordova platform regeneration, or manual device actions. When escalation is required, ask the developer to run the app through Cordova CLI, Android Studio, Xcode, Gradle, CocoaPods, or the relevant project tool and provide: - the exact build or runtime error; - crash reason, if available; - relevant logs; - device, simulator, or emulator details; - Cordova platform details; - reproduction steps. Do not stop after code changes. Before MCP-based validation, verify that Reteno MCP is connected in the same environment where you are running. After the app builds and runs, validate the integration through Reteno MCP: - find the contact; - verify `mobilePushToken`; - identify token type: `FCM` or `APNs`; - send a test push, when the capability is available and approved; - verify `DELIVERED`; - verify `CLICKED` after the push notification is opened. Validate every Reteno SDK feature that you integrate, modify, or are explicitly asked to verify. At minimum, for mobile push integration, validate contact creation, `mobilePushToken`, token type, test push, `DELIVERED`, and `CLICKED`. Run feature-specific validation when the current integration task includes additional SDK features such as In-App messages, custom events, deeplinks, custom push data, screen tracking, or `externalCustomerId`. If a step cannot be completed programmatically, ask for the required manual action and continue after confirmation. If an MCP capability is unavailable, document it as a missing MCP capability and continue with the remaining validation steps where possible. Return the final report using the format defined in this runbook. Do not mark the integration as complete until the required validation checks pass or a blocker is clearly documented. ## Source of Truth Use only official Reteno sources, official Cordova documentation, and the current customer application codebase for Cordova SDK integration. Do not duplicate the full Reteno documentation catalogue in this runbook. Use `llms.txt` to locate additional feature-specific documentation when needed. | Source | How to access it | Use it for | If unavailable | |---|---|---|---| | Customer application codebase | Inspect the current repository or workspace opened in the AI coding agent | Detect Cordova project structure, package manager, Cordova version, installed platforms, installed plugins, `config.xml`, `www/`, `platforms/`, `plugins/`, Firebase/APNs setup, push handlers, deeplinks, and files to modify | Ask the user to open the project in the AI coding agent or provide the required project files | | Reteno Cordova SDK | Open [Cordova SDK](https://docs.reteno.com/reference/cordova-sdk-setup) | Use it as the primary source of truth for Cordova SDK overview, plugin setup, initialization, and supported Cordova setup | Ask the developer to confirm Cordova setup requirements | | Reteno Cordova Android SDK Setup | Open [Cordova Android SDK Setup](https://docs.reteno.com/reference/cordova-android-sdk-setup) | Apply Android-specific Cordova setup: plugin installation, `config.xml`, `cordova-android`, Firebase / FCM setup, Android 13+ notification permission, Firebasex warning, custom FCM service, and deeplinks | Ask the developer to confirm Android Cordova setup requirements | | Reteno Cordova iOS SDK Setup | Open [Cordova iOS SDK Setup](https://docs.reteno.com/reference/cordova-ios-sdk-setup) | Apply iOS-specific Cordova setup: iOS deployment target, plugin installation, `config.xml`, Notification Service Extension, App Groups, extension Podfile, token handling mode, Firebase / FCM path, push permission, `setDeviceToken`, foreground/tap handlers, and deeplinks | Ask the developer to confirm iOS Cordova setup requirements | | Reteno Cordova User Information | Open [Cordova User Information](https://docs.reteno.com/reference/cordova-user-information) | Configure or verify user identification, `externalUserId`, user attributes, anonymous user attributes, multi-account attributes, `languageCode`, `timeZone`, and `marketId` support | Ask the developer to confirm user identification requirements | | Reteno Cordova User Behaviour | Open [Cordova User Behaviour](https://docs.reteno.com/reference/cordova-user-behaviour) | Configure and verify custom events, `RetenoPlugin.logEvent(...)`, `RetenoPlugin.forcePushData(...)`, and manual screen tracking through `RetenoPlugin.logScreenView(...)` | Ask the developer to confirm which behaviour events or screen views should be validated | | Cordova SDK Release Notes | Open [Cordova SDK Release Notes](https://docs.reteno.com/page/cordova-sdk-release-notes) | Check Cordova plugin versions, native SDK versions, release history, compatibility notes, migration-related changes, and known fixes | Ask the developer or platform owner to confirm the SDK version | | Reteno MCP Server Reference | Open [Reteno MCP Server](https://docs.reteno.com/reference/reteno-mcp-server) and verify whether Reteno MCP is connected in the AI agent environment | Discover available and authorized Reteno MCP capabilities; validate Reteno-side data when the required capability is available: contact lookup, `mobilePushToken` verification, token type validation, test push creation/sending, `DELIVERED` / `CLICKED` status checks, event verification, and feature-specific validation | Ask the developer to connect Reteno MCP when MCP-based validation is required. If MCP is unavailable or a required capability cannot provide reliable evidence, use an approved Reteno UI, backend, SDK-log, device-log, network-log, or manual fallback when available. Report the validation as blocked only when the required result cannot be verified through MCP or any approved fallback evidence. | | Reteno `llms.txt` | Open [Reteno `llms.txt`](https://docs.reteno.com/llms.txt) | Locate the latest Reteno documentation pages, SDK guides, API references, release notes, and feature-specific documentation | Use direct documentation links or ask the user to provide the relevant Reteno documentation page | | Mobile push error codes | Open [Mobile push error codes](https://docs.reteno.com/docs/error-codes-for-mob-push-notifications) | Troubleshoot failed test push validation, especially when push status `ERROR` is present | Ask the user or Support team to provide the relevant error code explanation | | Cordova documentation | Open [Apache Cordova Documentation](https://cordova.apache.org/docs/en/latest/) | Verify Cordova project structure, platform commands, plugin lifecycle, `config.xml`, platform folders, and build behavior | Ask the developer to confirm Cordova workflow and build setup | > **Note — Reteno MCP:** Reteno MCP must be connected in the same environment where the AI coding agent runs. Before using MCP for validation, discover which capabilities are available and authorized. Do not assume support for sending pushes, retrieving `DELIVERED` / `CLICKED` statuses, or managing In-App messages until capability discovery is completed. > **Note — Cordova generated platforms:** Cordova `platforms/` folders may be generated artifacts or committed source, depending on the project. Do not edit or regenerate platform folders until native ownership is confirmed. > **Note — Ionic and Capacitor:** If the project is an Ionic app, use the Ionic runbook first. If the project is Capacitor using Cordova plugin compatibility, do not assume Cordova hooks run. Capacitor-specific setup may require a separate Ionic/Capacitor flow. ## Agent Behaviour Rules Follow these rules throughout the Cordova SDK integration: - Inspect the project before making any code changes. - Detect the Cordova project structure, package manager, Cordova version, Cordova Android version, installed platforms, installed plugins, app entry point, native iOS/Android platform folders, Firebase setup, push notification setup, config files, and notification handlers from project files whenever possible. - Ask the user only for information that cannot be detected from the project, Reteno MCP, official Reteno documentation, or Cordova configuration. - Use the existing Cordova project setup. Do not switch package managers, Cordova platforms, app architecture, Firebase setup, push provider, native project ownership, or SDK versions unless the developer explicitly confirms this. - Treat Cordova as the highest-level framework. Do not start with Ionic, Capacitor, React Native, Flutter, Expo, native iOS, or native Android setup unless the project detection confirms that Cordova is not the correct runbook. - Preserve existing application logic. - Do not overwrite Cordova app startup, `deviceready` handlers, Cordova plugins, Firebase configuration, push notification handlers, deeplink handling, authentication flow, analytics logic, or existing native platform configuration. - Treat the Reteno `SDK_ACCESS_KEY` as client-side SDK configuration and follow the project's approved policy for storing or committing it. Do not unnecessarily expose the full SDK access key in prompts, logs, screenshots, tool output, or final reports. Treat Firebase Admin service account data, APNs private keys, certificates, Reteno REST API credentials, signing credentials, and other server-side credentials as hard secrets and never commit or expose them. - If the repository contains local agent instructions, such as `CLAUDE.md`, Cursor rules, or similar files, inspect them before making changes. If they conflict with this runbook, ask the developer to confirm which instruction has priority. - If a step cannot be completed programmatically, ask the developer to complete it manually. - After applying code changes, continue validation. - Use Reteno MCP for validation only after discovering that the required capability is available and authorized in the current environment. - Do not report the integration as complete until all required validation checks pass or a blocker is clearly documented. - Validate every Reteno SDK feature that is integrated, modified, or explicitly requested. - If validation fails, identify the failed step, troubleshoot, retry safe fixes, and document unresolved blockers in the final report. - Apply automatic fixes only when they are limited to JavaScript code, TypeScript code, Cordova configuration, plugin setup, dependency setup, native project configuration generated or owned by the current Cordova workflow, or available and authorized MCP capabilities. - Do not remove and re-add Cordova platforms unless the developer explicitly confirms this. - Do not run `cordova platform rm`, `cordova platform add`, `cordova prepare`, `cordova clean`, or regenerate native platform projects without confirming that this is safe for the project. - Do not change external app configuration, credentials, APNs/FCM setup, sandbox/production settings, Firebase project settings, Apple Developer account settings, signing, provisioning, or Reteno dashboard settings without explicit developer or admin confirmation. ## Cordova Project Detection Use this runbook for Cordova applications. The documented supported Cordova stack is Cordova `10.2` or later. Treat this as a supported-stack compatibility check. The platform-specific engine requirements remain authoritative for plugin installation: - `cordova-android >= 12.0.0` for Android; - `cordova-ios >= 8.0.0` for iOS. Do not automatically upgrade the Cordova CLI or platform versions. If the project uses an older Cordova version: - inspect whether the installed platform versions still satisfy the plugin engine constraints; - document the documentation/version mismatch; - ask the developer before upgrading the Cordova stack. Do not select this Cordova runbook merely because a project has `www/` or native `platforms/` folders. First determine the actual project type. Use the Cordova SDK flow when the project contains Cordova-specific files or configuration, such as: - `config.xml`; - `www/`; - `platforms/`; - `plugins/`; - `hooks/`; - `res/`; - `resources/`; - `package.json` with Cordova scripts; - `cordova` dependency; - `cordova-android`; - `cordova-ios`; - `cordova-plugin-*` dependencies; - `cordova-plugin-reteno`; - Cordova build scripts; - Cordova platform configuration. Before making changes, detect: - Cordova project structure; - package manager: npm, Yarn, pnpm, or another package manager; - Cordova CLI version, if available; - `cordova-android` version, if Android validation is included; - `cordova-ios` version, if iOS validation is included; - installed platforms: - Android; - iOS; - both; - installed plugins; - existing `cordova-plugin-reteno` usage, if any; - app entry point; - `deviceready` handler location; - existing Reteno initialization, if any; - `config.xml`; - `www/` source structure; - whether `platforms/` folders are committed; - whether `plugins/` folder is committed; - whether platform folders are generated and should not be edited manually; - Firebase / FCM setup; - `google-services.json`; - `GoogleService-Info.plist`; - Android package name / `applicationId`; - iOS bundle ID; - existing push notification setup; - existing push notification plugins; - `cordova-plugin-firebasex`, if installed; - existing deeplink plugin or routing layer; - existing custom event tracking; - existing authentication or user identification flow; - existing In-App message setup, if any. ### Cordova project classification Classify the project as one of the following: 1. **Pure Cordova app** The project has Cordova configuration and uses Cordova CLI/platforms directly. Use this Cordova runbook. 2. **Ionic app with Cordova runtime** The project has Ionic configuration and uses Cordova runtime. Use the Ionic runbook first. Apply Cordova-specific checks only where the Ionic runbook or project setup requires them. 3. **Ionic app with Capacitor runtime** The project has Ionic configuration and uses Capacitor. Do not use this Cordova runbook directly. Use the Ionic / Capacitor flow first because Capacitor does not execute Cordova plugin hooks in the same way as Cordova. 4. **Capacitor app using Cordova plugin compatibility layer** The project may install `cordova-plugin-reteno`, but native setup can differ from Cordova because Cordova hooks may not run. Do not assume Cordova automatic setup is applied. Use the Ionic / Capacitor flow or ask the developer to confirm the correct runbook. 5. **Non-Cordova project** If the project is React Native, Flutter, Expo, native iOS, native Android, Unity, or another framework, stop and use the corresponding runbook. ### Cordova template repository or validation scaffold Do not assume that every repository containing Cordova template code is already a runnable Cordova application. If the repository is an upstream Cordova application template, starter package, fixture, or source used by `cordova create`, verify whether the repository itself contains an actual application root with: - `config.xml`; - `www/`; - Cordova platform configuration; - application package metadata. If those files are intentionally absent because the repository is only a template: - do not retrofit Reteno directly into the upstream template source by default; - do not treat the template repository root as the application root; - ask the developer whether creating a temporary validation scaffold is approved. When a validation scaffold is approved: 1. create the runnable Cordova application through the project's normal Cordova workflow; 2. keep the original template source unchanged unless the developer explicitly asks to modify it; 3. treat the generated/scaffolded application directory as the `Application root`; 4. perform Reteno integration and validation inside that application; 5. document that the validation app is a scaffold and not necessarily a merge candidate for the upstream template repository. Do not report: ```text Merge readiness: Ready ``` for a temporary validation scaffold unless the developer explicitly intends to merge that scaffold into the repository. Use: ```text Merge readiness: Not applicable ``` when the scaffold exists only to validate that the Reteno Cordova integration flow works. Document in the final report: - repository root; - actual Cordova application root; - whether a validation scaffold was created; - whether original template sources were modified; - whether the scaffold is intended for merge. ### Effective Android and iOS application identity Do not assume that the Cordova `` value is always the final application identifier on both platforms. Inspect the effective identifiers separately for: - Android package name / `applicationId`; - iOS bundle identifier. Cordova projects may override the platform identifiers through project configuration such as: ```xml ``` The exact configuration may differ by Cordova version and project structure. Use the effective generated platform identifiers for Firebase, Reteno, signing, and validation checks. For Android, verify that: - `google-services.json` matches the effective Android application ID; - the Firebase Android client matches the effective Android identifier; - the selected Reteno Android app corresponds to that application. For iOS, verify that: - `GoogleService-Info.plist` matches the effective iOS bundle ID; - signing and provisioning match the effective iOS bundle ID; - App Group naming uses the effective main-app bundle ID; - the selected Reteno iOS app corresponds to that application. Do not assume Android and iOS identifiers must be identical. If sandbox validation changes either identifier: - document the original identifier; - document the temporary identifier; - validate each platform against its own Firebase and Reteno configuration; - require production revalidation with the real identifiers. ### Cordova platform ownership Before editing anything under `platforms/`, determine whether platform folders are generated artifacts or committed source. If platform folders are generated: - prefer changes in `config.xml`, plugin variables, hooks, or source files; - avoid manual edits under `platforms/`; - run `cordova prepare` only if approved. If platform folders are committed and manually maintained: - inspect native changes carefully; - preserve existing native configuration; - ask before regenerating platforms. ### Platform regeneration approval policy Running these commands may rewrite native platform files: ```bash cordova platform rm android cordova platform add android cordova platform rm ios cordova platform add ios cordova prepare cordova clean ``` Do not run them without explicit developer approval. Before running any platform regeneration or prepare command, document: - why it is required; - which platform will be affected; - whether `platforms/` is committed; - whether manual native changes may be overwritten; - whether the developer approves the action. If platform regeneration is not approved, continue only with non-blocked setup and report native configuration / runtime validation as blocked or pending. ### Durable native configuration for generated Cordova platforms When `platforms/` is generated or gitignored, a successful manual native edit inside `platforms/android` or `platforms/ios` is not automatically a durable integration fix. For every required native Reteno change, determine whether the change survives: ```bash cordova prepare cordova platform rm ios cordova platform add ios cordova platform rm android cordova platform add android ``` Do not run these commands only to test durability unless platform regeneration is explicitly approved. Examples of native changes that may need a reproducible source include: - Notification Service Extension target creation; - Notification Service Extension source files; - Notification Content Extension setup; - App Groups; - entitlements; - extension Podfile entries; - CocoaPods fixups; - Xcode build settings; - Firebase resource-file wiring; - signing-related project configuration; - Android manifest changes; - Gradle changes. When `platforms/` is generated, prefer a durable project-owned mechanism such as: - `config.xml`; - Cordova plugin variables; - Cordova hooks; - project-owned Cordova plugins; - repeatable setup scripts; - repeatable Xcode project patch scripts; - another developer-approved generation mechanism. If a required native change exists only inside generated `platforms/`: - report the change as non-durable; - document exactly what regeneration removes it; - do not report the integration as merge-ready unless the developer accepts the manual regeneration requirement; - recommend codifying the change before production use. After every approved platform regeneration or `cordova prepare`, re-verify: - Firebase client files; - App Groups; - entitlements; - Notification Service Extension; - Notification Content Extension, when required; - native Reteno dependency version; - extension dependency linkage; - signing/provisioning; - Android manifest / Firebase Messaging configuration; - any project-specific Reteno native fixups. Expected result: - required Reteno native configuration can be reproduced; - platform regeneration does not silently remove required integration changes; - temporary validation-only native edits are clearly reported as temporary. ## Change-safety boundaries Follow these change-safety rules throughout the Cordova integration. ### Cordova workflow preservation Preserve the existing Cordova workflow. Do not convert: - Cordova to Ionic; - Cordova to Capacitor; - Ionic Cordova to plain Cordova; - Capacitor to Cordova; - Cordova to native Android or native iOS; - npm to Yarn or pnpm; - Yarn to npm or pnpm; - pnpm to npm or Yarn. Do not generate, delete, or regenerate platform folders without explicit developer approval. ### Cordova plugin preservation Before editing Cordova configuration, inspect: - `config.xml`; - `package.json`; - `package-lock.json`; - `yarn.lock`; - `pnpm-lock.yaml`; - `plugins/`; - `platforms/`; - `hooks/`; - existing Cordova plugins; - existing plugin variables; - existing platform preferences; - environment-specific build scripts; - CI scripts. Do not overwrite existing plugin configuration. Add or update `cordova-plugin-reteno` in a way that preserves existing Cordova plugins and platform-specific configuration. ### Cordova startup preservation Before editing JavaScript or TypeScript source files, inspect: - `deviceready` listener; - app bootstrap file; - router initialization; - push plugin initialization; - Firebase plugin initialization; - authentication initialization; - analytics initialization; - deeplink initialization; - existing Reteno initialization, if present. Do not initialize Reteno before Cordova's native bridge is ready. Do not duplicate `RetenoPlugin.init(...)`. Do not move unrelated app startup logic unless the developer confirms this. ### Native platform preservation If native platform folders exist, inspect them before making changes. Inventory: - Android Gradle files; - AndroidManifest; - Firebase setup; - existing Firebase Messaging service; - iOS Podfile; - iOS project/workspace; - iOS entitlements; - Notification Service Extension; - Notification Content Extension; - App Groups; - existing notification delegates; - existing Firebase/APNs setup; - existing deeplink configuration. Do not remove or replace existing native handlers unless the official Cordova Reteno setup and developer confirmation require it. ### Pre-existing and collateral build compatibility changes Do not attribute every build failure discovered during Reteno integration to Reteno. When the integration requires a Cordova platform upgrade, newer Gradle / Android tooling, newer Xcode tooling, or another compatibility change, verify whether unrelated application plugins or existing project code also break as a result. Classify every significant compatibility fix as one of: - required directly by the Reteno SDK; - required by the selected Cordova platform version; - required by the current Android / iOS build toolchain; - pre-existing project defect; - collateral compatibility fix caused by upgrading the Cordova platform; - unrelated local environment fix. Examples may include: - deprecated or incompatible Cordova plugins; - old Gradle syntax; - missing dependencies used by existing project hooks; - plugin APIs incompatible with the selected Cordova platform; - startup code failing before Reteno initialization; - Java / Gradle / AGP compatibility problems; - old plugins requiring replacement or upgrade. Do not automatically upgrade, remove, or replace unrelated Cordova plugins. If a collateral plugin change is required to unblock Reteno validation: - explain why the existing plugin no longer works; - ask for developer approval; - preserve application behavior where possible; - document the exact plugin/version change; - validate the affected application functionality when feasible. If several unrelated product plugins must be upgraded or replaced, recommend a separate compatibility / maintenance review. Do not report those changes as Reteno SDK fixes. In the final report, separate: - Reteno integration changes; - Cordova platform compatibility changes; - pre-existing fixes; - collateral plugin upgrades; - recommended product QA follow-up. ### SDK demo app exclusion Do not use the SDK repository's example application as integration evidence. Do not copy its Firebase files, identifiers, access keys, signing configuration, provisioning, APNs credentials, or Reteno app configuration. Run integration validation only in the target application or an approved private test fork. Use separate non-production application IDs, Firebase projects, Reteno environments, and signing configuration for validation. ### Sandbox Firebase / package identity validation path You may use a sandbox Firebase / Reteno app configuration only when the developer explicitly approves this as a dry-run validation path. If you change package identity, bundle ID, Firebase client configuration, or Reteno app to match a demo, sample, or preconfigured sandbox setup: - document that this is a sandbox-only validation path; - do not report the branch as merge-ready or production-ready; - document the original package name / bundle ID; - document the temporary sandbox package name / bundle ID; - document which Firebase project and Reteno mobile app were used; - document any app behavior that may break because of the package identity change; - do not treat unrelated product behavior broken by the package identity change as a Reteno SDK defect; - require repeated validation before production use with the real package name / bundle ID, real Firebase project, real Reteno mobile app, real access key, and real platform config. A successful sandbox validation proves that the SDK flow can work in the selected environment. It does not prove that the production app configuration is complete. ### Retry and escalation policy Do not repeat the same failed action without a new hypothesis. Continue safe diagnostics while distinct testable causes remain. Escalate when external access, credentials, signing, Apple Developer account access, Firebase server configuration, Reteno dashboard changes, GUI interaction, Cordova platform regeneration, or manual device actions are required. Record attempted fixes and the first actionable error. Do not retry indefinitely. ## Required Inputs Ask the developer only for information that cannot be detected from the project files, Reteno MCP, official Reteno documentation, or Cordova project configuration. Before asking the developer, inspect the project and detect: - Cordova project structure; - `package.json`; - package manager; - Cordova CLI version, if available; - whether the detected Cordova version is `10.2` or later; - `cordova-android` version, if Android validation is included; - `cordova-ios` version, if iOS validation is included; - current `cordova-plugin-reteno` version, if installed; - `config.xml`; - `www/` source structure; - app entry point; - `deviceready` handler location; - installed Cordova platforms; - installed Cordova plugins; - native `platforms/android` and `platforms/ios` folders; - whether `platforms/` folders are committed or generated; - whether `plugins/` folder is committed or generated; - Firebase / FCM configuration; - `google-services.json`; - `GoogleService-Info.plist`; - Android package name / `applicationId`; - iOS bundle ID; - existing push notification handling; - existing Firebase / Firebasex plugin usage; - existing deeplink handling; - existing custom event tracking; - existing user identification or login flow; - existing In-App setup, if present. ### Required for Cordova SDK integration Ask for these values only if they are missing, unclear, or cannot be detected automatically: - Reteno SDK access key or approved project configuration method for providing it; - Reteno app or environment name; - environment type: - development; - staging; - production; - target validation platform: - Android only; - iOS only; - both Android and iOS; - Cordova project type, if it cannot be detected: - pure Cordova app; - Ionic app using Cordova runtime; - Ionic app using Capacitor runtime; - Capacitor app using Cordova plugin compatibility layer; - non-Cordova project; - confirmation whether this Cordova runbook or the Ionic runbook should be used; - confirmation whether `platforms/` folders are committed source or generated artifacts; - confirmation whether `cordova prepare` is allowed; - confirmation whether `cordova platform rm/add` is allowed; - confirmation whether plugin reinstall is allowed; - confirmation which Reteno mobile app should be used for each target platform; - confirmation whether the selected Reteno mobile app is configured for `FCM` or `APNs`; - confirmation of which SDK features must be enabled: - mobile push; - custom events; - user identification; - In-App messages; - deeplinks; - custom push data; - screen tracking. ### Required for Cordova Android push setup and validation Ask for these values only when Android validation is included and the information is missing, unclear, or cannot be detected automatically: - confirmation that `cordova-android` version is `12.0.0` or higher; - confirmation that Firebase / FCM is configured for Android; - confirmation that `google-services.json` belongs to the correct Firebase project; - confirmation that `google-services.json` matches the effective Android package name / `applicationId`; - confirmation that Google Services Gradle plugin is applied; - confirmation whether `cordova-plugin-firebasex` is installed; - confirmation whether Firebasex is required for app-specific behavior; - confirmation whether the app has a custom `FirebaseMessagingService`; - confirmation that Android 13+ notification permission can be requested at runtime; - confirmation that the selected Reteno mobile app is configured with `FCM` token type; - confirmation that Reteno MCP is connected and available in the AI coding agent environment; - confirmation that the signed-in Reteno account has access to the selected Reteno app/environment; - access to the selected Android test environment: - Android emulator; - physical Android device; - another supported environment; - confirmation that push validation is supported in the selected Android test environment; - confirmation that the developer or QA engineer can open the delivered test push notification if you cannot interact with the environment directly. ### Required for Cordova iOS push setup and validation Ask for these values only when iOS validation is included and the information is missing, unclear, or cannot be detected automatically: - confirmation that iOS deployment target is `15.0` or higher; - confirmation that Xcode `15.0` or higher is available; - confirmation that Swift `5.7` or higher is supported by the project; - iOS bundle ID; - push route: - direct APNs; - Firebase / FCM with APNs transport; - selected `IOS_DEVICE_TOKEN_HANDLING_MODE`: - `manual`; - `automatic`; - confirmation whether `RetenoPlugin.setDeviceToken(token)` is required; - confirmation that `GoogleService-Info.plist` belongs to the correct Firebase project, if iOS uses Firebase / FCM; - confirmation that Firebase has valid APNs credentials, if iOS uses Firebase / FCM; - confirmation that Reteno uses the corresponding Firebase project, if iOS uses Firebase / FCM; - confirmation that APNs sandbox / production route is correct, if direct APNs is used; - confirmation that Push Notifications capability can be configured; - confirmation that App Groups can be configured; - confirmation that Notification Service Extension can be created or updated; - confirmation that Notification Content Extension can be created or updated, if rich push UI is required; - confirmation that extension Podfile changes are allowed; - confirmation that Apple signing / provisioning can be updated by the developer or admin; - access to the selected iOS test environment: - iOS simulator, if supported and confirmed by the developer; - physical iOS device; - another supported iOS test environment; - confirmation that push validation is supported in the selected iOS test environment; - confirmation that the developer or QA engineer can open the delivered test push notification if you cannot interact with the simulator or device directly. ### Required for feature-specific custom event validation Ask for these inputs when custom event validation is part of the current integration task: - confirmation that a test custom event can be added to the Cordova app code; - confirmed event name for validation; - access to Reteno MCP, Reteno UI, backend data, event log, SDK logs, device logs, or API response to verify that the event was received and assigned to the correct contact. Do not hardcode a required event name unless the developer confirms it. ### Required for feature-specific In-App validation Ask for these inputs only when In-App validation is part of the current integration task: - confirmation whether an In-App message already exists or should be created for validation; - existing In-App message name or ID, if an existing In-App message should be used; - confirmation whether the default In-App message is available in the selected Reteno account; - confirmed trigger type: - app open; - uniquely named event; - mobile-push + In-App; - another approved trigger; - confirmed trigger event name, if event-triggered In-App validation is part of the current integration task; - access to the selected test environment where the In-App message should appear; - confirmation that the developer, admin, or QA engineer can create, configure, publish, open, or click the In-App message manually if MCP cannot do it. Do not create, update, publish, configure, attach, or send In-App messages without explicit developer or admin approval. ### Required for feature-specific externalCustomerId validation Ask for these values when the current integration task includes login, registration, user identification, or explicitly asks to validate `externalCustomerId`. For `externalCustomerId` validation, ask for: - confirmation that login or registration flow should be tested; - test login or registration credentials, if required; - expected stable customer ID format; - confirmation that you, developer, user, or QA engineer can complete the login or registration flow. Do not validate `externalCustomerId` unless this check is part of the current integration task. ### Required for deeplink or custom push data validation Ask for these values only when deeplink or custom push data validation is part of the current integration task: - expected deeplink format; - expected Cordova route / WebView navigation behavior; - expected custom push payload fields; - expected destination screen or app behavior; - app-level deeplink solution: - custom URL scheme; - Universal Links; - Android App Links; - Branch.io; - another routing provider; - whether the test should cover foreground, background, and terminated app states. ## Security rules Distinguish client-side SDK configuration from hard server-side credentials. ### SDK access key handling `SDK_ACCESS_KEY` is client-side Reteno SDK configuration. For Cordova, it may be configured through: - plugin installation variable; - `config.xml`; - approved local environment or build-time configuration; - JavaScript initialization when supported and approved. The plugin may embed the SDK access key into generated native application configuration. Whether the SDK access key is committed to the repository is governed by the project’s policy. It is safe to verify: - that the `SDK_ACCESS_KEY` configuration entry exists; - that the expected variable name is used; - that the value is connected to the selected plugin configuration; - that `config.xml` or another approved source contains the expected configuration entry. Do not unnecessarily print the full SDK access key value. Prefer redacted output when displaying configuration. If the SDK access key was shared through chat, logs, prompts, screenshots, terminal output, or tool output, document the exposure and follow the project policy for rotation. ### Hard server-side secrets The following remain hard secrets and must never be committed, printed, copied into prompts, or included in the final report: - Firebase Admin service account JSON; - APNs authentication private keys; - APNs certificates and private key material; - signing credentials; - Reteno REST API credentials; - CI/CD secret values; - other private server credentials. Do not run broad commands that may expose hard secrets, such as: ```bash cat grep -R SERVICE_ACCOUNT . grep -R PRIVATE_KEY . grep -R APNS_AUTH_KEY . ``` unless the command is intentionally scoped to filenames, configuration names, or redacted output. When checking Firebase/APNs server credentials: - verify configuration existence without printing the credential value; - use filenames, metadata, or redacted output; - never include full secret material in logs, screenshots, terminal output, prompts, or final reports. If a hard secret is accidentally exposed: - report the exposure; - mark it as a security warning / action required; - recommend immediate rotation in the relevant provider; - do not repeat the value in the final report. ### Firebase and APNs security distinction Distinguish between client configuration and server credentials. Client configuration may include: - Android Firebase client configuration; - Apple-platform Firebase client configuration; - Firebase client API keys. Client configuration may be included in the repository only when this matches the project policy. Server credentials must never be committed, printed, copied into prompts, or included in the final report. Server credentials include: - Firebase Admin service account JSON; - APNs authentication keys; - APNs certificates; - private keys; - Reteno REST API credentials. If Reteno server-side Firebase or APNs configuration is missing, ask the developer or admin to configure it in the Reteno dashboard. Do not ask the developer to paste server credentials into the chat. ## Developer Preparation Checklist Before starting Cordova SDK integration, ask the developer to prepare or confirm the items below. You must not ask for all values upfront if they can be detected from the project. However, the developer should make sure that the required project access, credentials, environment, and validation tools are available before the integration run starts. ### 1. Project access The developer should provide or confirm: - access to the Cordova project repository; - the correct branch for the integration run; - whether the current branch can be modified; - whether a temporary local branch should be created; - whether the working tree is clean or contains unrelated changes; - whether you are allowed to install dependencies; - whether you are allowed to run Cordova CLI commands; - whether you are allowed to run `cordova prepare`; - whether you are allowed to run `cordova platform rm/add`. Do not continue with file modifications if branch or working tree safety is unclear. ### 2. Cordova workflow and platform ownership The developer should confirm: - Cordova project type: - pure Cordova app; - Ionic app using Cordova runtime; - Ionic app using Capacitor runtime; - Capacitor app using Cordova plugin compatibility layer; - non-Cordova project; - installed Cordova platforms: - Android; - iOS; - both; - whether `platforms/` folders are committed source or generated artifacts; - whether `plugins/` folder is committed or generated; - whether Cordova platform regeneration is allowed; - whether plugin reinstall is allowed; - whether manual native changes may be overwritten by Cordova prepare or platform regeneration; - which Cordova build commands should be used. Do not run `cordova platform rm`, `cordova platform add`, `cordova prepare`, or `cordova clean` without explicit developer approval. ### 3. Reteno app and SDK access key The developer should confirm: - selected Reteno organization / workspace; - selected Reteno app/environment; - whether the Reteno app is for Android, iOS, or both; - token type configured for each selected Reteno app: - Android: `FCM`; - iOS: `APNs` or `FCM`; - whether development and production apps are separated; - approved method for providing the Reteno SDK access key; - whether debug mode may be enabled during the integration run. Handle the Reteno SDK access key according to the project's approved configuration and repository policy. Do not unnecessarily expose the full SDK access key in prompts, logs, screenshots, tool output, or final reports. ### 4. Android / Firebase setup For Android validation, the developer should confirm: - `cordova-android` version is `12.0.0` or higher; - Firebase project; - Android package name / `applicationId`; - `google-services.json`; - Reteno server-side Firebase configuration; - Google Services Gradle plugin can be applied or is already applied; - whether `cordova-plugin-firebasex` is installed; - whether Firebasex is required for app-specific behavior; - whether a custom `FirebaseMessagingService` exists; - Android test device or emulator; - Android 13+ notification permission can be requested at runtime. ### 5. iOS / APNs / Firebase setup For iOS validation, the developer should confirm: - iOS deployment target is `15.0` or higher; - Xcode `15.0` or higher is available; - Swift `5.7` or higher is supported; - iOS bundle ID; - push route: - direct APNs; - Firebase / FCM with APNs transport; - selected `IOS_DEVICE_TOKEN_HANDLING_MODE`: - `manual`; - `automatic`; - `GoogleService-Info.plist`, if Firebase / FCM is used; - Firebase APNs credentials, if Firebase / FCM is used; - APNs sandbox / production route, if direct APNs is used; - Apple Developer Team ID, if required; - Push Notifications capability; - App Groups capability; - Notification Service Extension setup; - Notification Content Extension setup, if rich push UI is enabled; - extension Podfile changes are allowed; - signing/provisioning can be updated by the developer or admin. ### 6. Test environment The developer should confirm the selected test environment: - Android emulator; - physical Android device; - iOS simulator, if supported and confirmed by the developer; - physical iOS device; - local Cordova build; - CI build; - another supported environment. The developer should confirm that: - the app can be built and installed; - Cordova native bridge works; - `deviceready` event fires; - the app can request push permission; - push notifications can be enabled; - the developer or QA engineer can open the delivered test push notification if you cannot interact with the device directly; - the developer or QA engineer can complete login or registration if user identification validation is required. ### 7. Reteno MCP The developer should confirm: - Reteno MCP is connected in the same environment where the AI coding agent runs; - the signed-in Reteno account has access to the selected organization / workspace; - the signed-in Reteno account has access to the selected Reteno app; - MCP capabilities can be discovered before validation; - manual Reteno UI fallback is available if a required MCP capability is missing. Do not mark the integration as complete when a required Reteno-side result cannot be verified through Reteno MCP or any approved fallback evidence. Missing MCP access alone is not a blocker when the required result can be independently verified through Reteno UI, backend data, SDK logs, device logs, redacted network evidence, or developer / QA confirmation. ### 8. Build and runtime logs If you cannot build or run the app after safe diagnostics, or if the issue requires local environment access, the developer should provide: - exact Cordova CLI build error; - Android Studio / Gradle logs, if Android build fails; - Xcode / CocoaPods logs, if iOS build fails; - device, simulator, or emulator details; - Cordova platform details; - plugin list; - reproduction steps; - confirmation whether the issue is pre-existing or introduced by the integration. ## Cordova SDK Integration Workflow Follow this workflow for Cordova SDK integration. ### 1. Inspect the project Before making changes, inspect the Cordova project. Identify: - project structure; - package manager; - Cordova CLI version, if available; - `cordova-android` version, if Android validation is included; - `cordova-ios` version, if iOS validation is included; - `config.xml`; - `package.json`; - installed platforms; - installed plugins; - current `cordova-plugin-reteno` version, if installed; - `www/` source structure; - app entry point; - `deviceready` handler location; - existing Reteno initialization, if any; - native `platforms/android` and `platforms/ios` folders; - whether `platforms/` folders are committed; - Firebase / FCM setup; - existing `google-services.json`; - existing `GoogleService-Info.plist`; - existing push notification setup; - existing deeplink handling; - existing authentication or user identification flow; - existing In-App setup, if any; - files that may need to be updated. Do not ask the developer for information that can be detected from project files. ### 2. Confirm Cordova project type Classify the project before installing or configuring the SDK. Use one of these classifications: - pure Cordova app; - Ionic app using Cordova runtime; - Ionic app using Capacitor runtime; - Capacitor app using Cordova plugin compatibility layer; - non-Cordova project. If the project is Ionic, do not automatically use this Cordova runbook. Use the Ionic runbook first and apply Cordova-specific checks only where the Ionic flow requires them. If the project is Capacitor using Cordova plugin compatibility layer, do not assume Cordova hooks run. Ask the developer whether to continue with Ionic / Capacitor flow. ### 3. Check whether Reteno Cordova SDK is already installed If `cordova-plugin-reteno` is already installed, do not reinstall it from scratch. Instead: - detect the current plugin version from project files, if possible; - check plugin variables in `config.xml`; - check installed plugins; - check whether Android setup is complete; - check whether iOS setup is complete; - check whether initialization is already called from `deviceready`; - check whether push handling is configured; - check whether the current integration is incomplete, outdated, or misconfigured. If `cordova-plugin-reteno` is not installed, continue with a new Cordova SDK integration flow. ### 4. Check SDK version and release notes Before installing, updating, or troubleshooting the Reteno Cordova SDK: - detect the current plugin version from project files, if installed; - check official Cordova SDK setup documentation; - check Cordova SDK Release Notes; - check package registry metadata, if needed; - check whether the issue may be related to an outdated SDK version, compatibility issue, migration requirement, or known fixed issue. Use the latest stable `cordova-plugin-reteno` version recommended by official Reteno documentation or package metadata. Do not use pre-release, beta, alpha, or release-candidate versions unless the developer explicitly asks for it. If documentation, release notes, and package registry versions differ, document the mismatch and ask the developer or platform owner which version to use. ### 5. Install or configure the Cordova plugin Install `cordova-plugin-reteno` using the existing project workflow. Do not switch package managers. Do not generate another package manager's lockfile. Example: ```bash cordova plugin add cordova-plugin-reteno --variable SDK_ACCESS_KEY=YOUR_KEY ``` Or configure plugin variables in `config.xml` when approved by the project policy: ```xml ``` Do not commit a real SDK access key unless this matches the project’s approved policy. If plugin variables are changed, Cordova may require plugin reinstall or platform prepare. Do not run plugin reinstall or platform regeneration without developer approval. ### 6. Initialize Reteno after `deviceready` Initialize Reteno only after Cordova native bridge is ready. Use the existing app startup structure. Do not initialize Reteno before `deviceready`. Do not duplicate `RetenoPlugin.init(...)`. Example structure: ```js document.addEventListener('deviceready', onDeviceReady, false); function onDeviceReady() { RetenoPlugin.init({ isDebugMode: false, pauseInAppMessages: false }) .then(() => { console.log('Reteno init: OK'); }) .catch((err) => { console.error('Reteno init: ERROR', err); }); } ``` If the project already has a centralized bootstrap file, initialize Reteno there. Expected result: - initialization happens once; - initialization happens after `deviceready`; - SDK access key is available; - Cordova native bridge is ready; - existing app startup logic is preserved. ### 7. Request notification permission When mobile push validation is included, request notification permission through the Cordova plugin method: ```js RetenoPlugin.requestNotificationPermission() .then((grantedInt) => { // 1 - granted, 0 - declined }) .catch((err) => { console.error(err); }); ``` Preserve the existing permission-prompt UX. Do not show a duplicate permission prompt if the app already has an approved push permission flow. Document where permission is requested in the final report. ### 8. Configure Android, if Android validation is included Follow [Android-specific Cordova setup](#android-specific-cordova-setup). ### 9. Configure iOS, if iOS validation is included Follow [iOS-specific Cordova setup](#ios-specific-cordova-setup). ### 10. Configure push handling Follow [Cordova push handling](#cordova-push-handling). ### 11. Configure user identification, if required Follow [Cordova user identification](#cordova-user-identification). ### 12. Prepare platforms only when approved Run `cordova prepare` only when the developer explicitly approves it or confirms that platform folders are generated artifacts. Before running prepare, report: - why prepare is required; - which platform will be affected; - whether `platforms/` folders are committed; - whether manual native changes may be overwritten; - whether the developer approves the action. Example: ```bash cordova prepare android ``` ```bash cordova prepare ios ``` Do not run platform remove/add unless explicitly approved. ### 13. Build and run the application Use the selected supported test environment. Possible build/run commands may include: ```bash cordova build android ``` ```bash cordova run android ``` ```bash cordova build ios ``` ```bash cordova run ios ``` Use the project’s existing scripts when available. If build/run fails, do not repeat the same failed action without a new hypothesis. Continue safe diagnostics while distinct testable causes remain. Escalate when the issue requires local environment access, external access, credentials, signing, Apple Developer account access, Firebase server configuration, Reteno dashboard changes, GUI interaction, Cordova platform regeneration, or manual device actions. When escalation is required, ask the developer to run the app through Cordova CLI, Android Studio, Xcode, Gradle, CocoaPods, or the relevant project tool and provide: - exact build or runtime error; - crash reason, if available; - Cordova CLI logs; - Gradle logs, if Android build fails; - Xcode / CocoaPods logs, if iOS build fails; - relevant native logs; - device, simulator, or emulator details; - reproduction steps. ### 14. Continue validation After the app builds and runs, continue with [MCP Capability Discovery and Validation](#mcp-capability-discovery-and-validation). Do not mark the integration as complete until required validation checks pass or a blocker is clearly documented. ## Android-specific Cordova setup Use this section when Android validation is included. Follow the official Reteno Cordova Android SDK setup. ### 1. Verify Android prerequisites Before Android setup, verify: - `cordova-android` version; - Android package name / `applicationId`; - `google-services.json`; - Firebase / FCM setup; - Reteno app configured for Android / FCM; - Android 13+ notification permission flow; - whether `platforms/android` exists; - whether `platforms/android` is committed; - whether `cordova prepare android` is approved; - whether `cordova platform rm/add android` is approved; - selected Android test environment. ### 2. Cordova Android version Reteno Cordova Android setup requires: ```text cordova-android >= 12.0.0 ``` Older Cordova Android platforms may refuse to install the plugin or may not support the required Android configuration. Do not upgrade `cordova-android` without explicit developer approval. Treat a Cordova Android platform upgrade as a product/build compatibility decision. Document the detected `cordova-android` version in the final report. ### 3. Install or configure plugin for Android Use the project’s existing plugin management approach. Example: ```bash cordova plugin add cordova-plugin-reteno --variable SDK_ACCESS_KEY=YOUR_KEY ``` Or configure in `config.xml`: ```xml ``` Do not commit a real SDK access key unless this matches the project’s approved policy. If plugin variables are changed after installation, Cordova may require plugin reinstall or platform regeneration. Do not run plugin reinstall or platform regeneration without developer approval. ### 4. Android Firebase / FCM setup Distinguish between the Firebase client configuration source and the generated Cordova Android copy. #### Source / configuration location The developer-provided `google-services.json` should exist in one of the locations supported by the Reteno Cordova plugin hook: ```text /google-services.json /resources/google-services.json /resources/android/google-services.json ``` The exact source location depends on the current Cordova project structure. Verify that the source file: - belongs to the correct Firebase project; - matches the effective Android package name / `applicationId`; - is stored in the project-approved location. #### Generated verification location After plugin installation, `cordova prepare`, or Android platform preparation, verify the generated copy at: ```text platforms/android/app/google-services.json ``` The Reteno Cordova plugin setup hook copies the source Firebase configuration into the generated Android platform project. Treat the source location as the configuration source of truth. Do not manually fix a missing or mismatched Firebase configuration only inside: ```text platforms/android/app/google-services.json ``` when `platforms/android` is generated. Manual edits inside the generated platform folder may be overwritten by the next: ```text cordova prepare cordova platform add cordova platform regeneration ``` If the generated copy is missing or incorrect: 1. inspect the source `google-services.json`; 2. correct or replace the source file with developer approval; 3. run the approved Cordova prepare/build flow; 4. verify the generated copy afterward. Do not invent or manually reconstruct `google-services.json`. ### 5. Android 13+ notification permission For Android 13+ and `targetSdkVersion >= 33`, runtime notification permission is required. The plugin may inject `POST_NOTIFICATIONS` into the manifest, but the app still needs to request permission at runtime. Use: ```js RetenoPlugin.requestNotificationPermission() .then((grantedInt) => { // 1 - granted, 0 - declined }) .catch((err) => { console.error(err); }); ``` Preserve existing permission prompt UX. Do not duplicate prompts. Document the permission request location in the final report. ### 6. Firebasex conflict check If `cordova-plugin-firebasex` is installed, inspect whether it registers its own `FirebaseMessagingService`. On Android, only one service receives `com.google.firebase.MESSAGING_EVENT`. Firebasex may prevent Reteno from receiving FCM callbacks. Do not remove Firebasex automatically. If Firebasex is required for app-specific behavior: - preserve it; - document the possible conflict; - ask an Android/Cordova SME to confirm the correct integration path; - verify whether Reteno still receives token and push callbacks. If Firebasex was installed only for push delivery and Reteno should handle push instead, ask the developer whether Firebasex can be removed or reconfigured. ### 7. Custom Firebase Messaging Service Most Cordova apps do not need a custom `FirebaseMessagingService`. If custom native FCM handling is required, use the official Reteno Cordova Android setup. The custom service must extend Reteno’s Firebase messaging service and call `super` methods. Do not create duplicate `MESSAGING_EVENT` services. Do not replace existing app-specific native logic without developer approval. ### 8. Android build and run Build and run with: ```bash cordova build android ``` ```bash cordova run android ``` or with the project’s existing Android build command. Expected result: - app builds; - app installs; - app launches; - `deviceready` fires; - SDK initializes; - contact is created; - `mobilePushToken` is assigned; - token type is `FCM`; - test push can be sent and validated. ## iOS-specific Cordova setup Use this section when iOS validation is included. Follow the official Reteno Cordova iOS SDK setup. ### 1. Verify iOS prerequisites Before iOS setup, verify: - `cordova-ios` version; - whether `cordova-ios` is `8.0.0` or higher; - iOS deployment target; - Xcode version; - Swift version; - iOS bundle identifier; - push route: - direct APNs; - Firebase / FCM with APNs transport; - selected `IOS_DEVICE_TOKEN_HANDLING_MODE`: - `manual`; - `automatic`; - `GoogleService-Info.plist`, if Firebase / FCM is used; - Apple Developer Team ID, if required; - Push Notifications capability; - App Groups capability; - Notification Service Extension setup; - Notification Content Extension setup, if rich push UI is enabled; - extension Podfile setup; - selected iOS test environment. Reteno Cordova iOS integration requires: ```text cordova-ios >= 8.0.0 ``` The installed `cordova-plugin-reteno` declares this requirement through its Cordova engine constraint. If `cordova-ios` is lower than `8.0.0`: - do not continue with normal iOS plugin setup; - do not upgrade `cordova-ios` automatically; - report the compatibility issue; - ask the developer to approve the platform upgrade. Treat a `cordova-ios` upgrade as a project compatibility decision. ### 2. Minimum iOS requirements Reteno Cordova iOS setup requires: ```text iOS 15.0+ Xcode 15.0+ Swift 5.7+ ``` In `config.xml`, verify or add: ```xml ``` Do not raise the iOS deployment target without developer approval. Treat deployment target increase as a product compatibility decision. If `pod install` fails because a higher minimum deployment target is required, ask the developer to approve raising deployment target to `15.0` or higher. ### 3. Install or configure plugin for iOS Use the project’s existing plugin management approach. Example: ```bash cordova plugin add cordova-plugin-reteno --variable SDK_ACCESS_KEY=YOUR_KEY ``` Or configure in `config.xml`: ```xml ``` Do not commit a real SDK access key unless this matches the project’s approved policy. ### 4. iOS token handling mode For Cordova iOS, explicitly choose and document `IOS_DEVICE_TOKEN_HANDLING_MODE`. Supported modes: ```text manual automatic ``` Use: ```xml ``` or: ```xml ``` Use `manual` when the app uses Firebase / FCM token forwarding or when another SDK/plugin owns token retrieval. Use `automatic` only when the app intentionally uses APNs-only token handling by the native Reteno SDK. The mode is read from iOS preferences during `RetenoPlugin.init()`. It cannot be changed at runtime from JavaScript after plugin start. If this preference changes, run `cordova prepare ios` and rebuild the iOS app after developer approval. Document the selected mode in the final report. ### 5. Firebase / FCM on iOS If the app uses Firebase / FCM for iOS push delivery: - verify `GoogleService-Info.plist`; - verify that it belongs to the correct Firebase project and iOS bundle ID; - verify Firebase has valid APNs credentials; - verify Reteno uses the corresponding Firebase project; - verify APNs and FCM tokens are not mixed; - use `IOS_DEVICE_TOKEN_HANDLING_MODE=manual` unless official docs and developer confirmation require otherwise. The plugin can forward Firebase Messaging token updates to Reteno when manual mode and Firebase setup are correct. If another plugin obtains the FCM token and the automatic forwarding path does not work, forward the token manually: ```js RetenoPlugin.setDeviceToken(token) .then(() => { console.log('Reteno setDeviceToken: OK'); }) .catch((err) => { console.error('Reteno setDeviceToken: ERROR', err); }); ``` Do not mark iOS FCM push setup as complete until the selected token path is verified. #### iOS Firebase client-file source and target wiring For the iOS Firebase / FCM route, distinguish the project-owned source `GoogleService-Info.plist` from its generated Xcode-project representation. The source file may be stored in a project-approved location such as: ```text GoogleService-Info.plist resources/ios/GoogleService-Info.plist another project-owned environment/configuration location ``` Do not require one fixed source path for every Cordova application. Verify that the project has a reproducible mechanism that adds the correct file to the main iOS application target. Depending on the project, this may use: - Cordova `config.xml` resource configuration; - a project-owned Cordova plugin; - an existing Cordova hook; - another approved Cordova-native generation mechanism. Example Cordova resource configuration may resemble: ```xml

``` Treat this as an example only. Preserve the project's existing Cordova configuration style. Verify after the approved Cordova prepare/build flow that: - the correct `GoogleService-Info.plist` exists in the generated iOS project; - it is included in the main application target; - its bundle identifier matches the effective iOS bundle ID; - it belongs to the expected Firebase project. If `platforms/ios` is generated, do not rely on manually dragging the plist into Xcode as the permanent configuration source. Prefer reproducible Cordova configuration, a hook, or another project-owned mechanism. ### 6. Direct APNs on iOS If the app uses direct APNs: - verify selected Reteno app is configured for APNs; - verify token type is `APNs`; - verify APNs sandbox / production route; - use `IOS_DEVICE_TOKEN_HANDLING_MODE=automatic` only when APNs-only token handling is intended and confirmed. Do not treat missing `DELIVERED` as an SDK integration issue until APNs sandbox/production routing is confirmed. ### 7. iOS App Group naming Use the required Reteno shared-storage App Group format: ```text group..reteno-local-storage ``` Use the main app bundle ID. Do not use the Notification Service Extension bundle ID. Do not add an extension suffix. Example: ```text Main app bundle ID: com.example.app Required Reteno App Group: group.com.example.app.reteno-local-storage ``` Apply the same App Group to: - the main app target; - Notification Service Extension; - Notification Content Extension, if created. Expected result: - all required targets share the same Reteno App Group; - the App Group uses the main app bundle ID; - the App Group does not use the extension bundle ID; - Reteno shared storage works between app and extensions. ### 8. Notification Service Extension and extension Podfile For iOS push delivery and rich push behavior, verify Notification Service Extension setup. The plugin wires `Reteno` pod into the main iOS target automatically. For extension targets, add the Reteno pod manually in `platforms/ios/Podfile` inside the main target block. Example structure: ```ruby target 'App' do # ... existing pods ... target 'NotificationServiceExtension' do inherit! :search_paths pod 'Reteno', '2.7.3' end target 'NotificationContentExtension' do inherit! :search_paths pod 'Reteno', '2.7.3' end end ``` The Reteno pod version used by every extension target must exactly match the native iOS Reteno pod version declared by the currently installed Cordova plugin. Before editing the extension Podfile, inspect: ```text plugins/cordova-plugin-reteno/plugin.xml ``` Find the Reteno pod declaration: ```xml ``` Use exactly the same `spec` value for: - `NotificationServiceExtension`; - `NotificationContentExtension`, when used. Do not leave the extension pod unpinned. Do not hardcode an older Reteno pod version from this runbook if the currently installed `plugin.xml` declares a different version. Expected result: - the main application target and extension targets use the same native Reteno iOS SDK version; - CocoaPods does not resolve different Reteno SDK versions inside the same workspace. Do not assume extension targets receive Reteno automatically from the main plugin setup. After Podfile changes, run CocoaPods commands only when allowed by the developer. If `pod install` fails because specs are outdated, use: ```bash pod install --repo-update ``` from the `platforms/ios` directory, or pass `-- --repo-update` to `cordova build ios` when appropriate. ### 8.1. Verify Notification Service Extension Reteno linkage A correct Reteno entry in the extension Podfile does not by itself prove that the Notification Service Extension is successfully linked against the Reteno native SDK. After CocoaPods resolution, build the Notification Service Extension target and verify that the extension links successfully. If the extension has the correct: ```ruby pod 'Reteno', '' ``` but fails at the linker stage, inspect: - the Notification Service Extension target build settings; - CocoaPods-generated `.xcconfig` files; - inherited search paths; - `LIBRARY_SEARCH_PATHS`; - `FRAMEWORK_SEARCH_PATHS`, when applicable; - `OTHER_LDFLAGS`; - whether the Reteno pod/product is actually linked to the extension target; - whether the extension target is using the expected CocoaPods configuration. Do not assume that: ```ruby inherit! :search_paths ``` always provides every linker setting required by every Cordova / CocoaPods project structure. Do not add arbitrary linker flags globally. If a linker adjustment is required: - base it on the actual generated CocoaPods configuration and linker error; - scope the change to the affected extension target; - preserve existing linker settings; - obtain developer approval for native project changes; - rebuild the extension and verify that it links successfully. If `platforms/ios` is generated or gitignored, do not leave the required linker adjustment only as a manual Xcode edit. Codify it through a project-approved reproducible hook/script/plugin mechanism when possible. Document in the final report: - whether the extension Reteno pod was present; - whether the extension linked successfully without additional fixups; - any linker/build-setting fix required; - whether that fix survives Cordova platform regeneration. ### 9. iOS permission request When mobile push validation is included, request notification permission through the Cordova plugin method: ```js RetenoPlugin.requestNotificationPermission() .then((grantedInt) => { // 1 - granted, 0 - declined }) .catch((err) => { console.error(err); }); ``` Preserve existing permission prompt UX. Do not duplicate prompts. Document where permission is requested in the final report. ### 10. iOS foreground and tap behavior If the app needs custom foreground or tap handling, configure it from JavaScript only when official docs and developer confirmation require it. Example: ```js RetenoPlugin.setWillPresentNotificationOptions({ options: ['badge', 'sound', 'banner'], emitEvent: true }); RetenoPlugin.setDidReceiveNotificationResponseHandler({ enabled: true, emitEvent: true }); ``` When `emitEvent: true`, the plugin may emit notification events such as push received or notification clicked events. Preserve existing app notification handling. Do not create duplicate routing. ### 11. iOS build and run Build and run with: ```bash cordova build ios ``` ```bash cordova run ios ``` or with the project’s existing iOS build command. Expected result: - app builds; - app installs; - app launches; - `deviceready` fires; - SDK initializes; - contact is created; - `mobilePushToken` is assigned; - token type is `APNs` or `FCM`, depending on selected route; - test push can be sent and validated. ## Cordova push handling Use this section when mobile push validation is included. Follow the official Reteno Cordova push handling documentation and the selected platform setup. ### Cordova push handling API reference When push handling, custom push data, notification opening, cold-start behavior, or action buttons are part of the current integration task, verify the actual API exposed by the installed `cordova-plugin-reteno` version. Relevant methods include: ```js RetenoPlugin.getInitialNotification() RetenoPlugin.setOnRetenoPushReceivedListener() RetenoPlugin.removeOnRetenoPushReceivedListener() RetenoPlugin.setOnRetenoNotificationClickedListener() RetenoPlugin.removeOnRetenoNotificationClickedListener() RetenoPlugin.setOnRetenoPushDismissedListener() RetenoPlugin.removeOnRetenoPushDismissedListener() RetenoPlugin.setOnRetenoCustomPushReceivedListener() RetenoPlugin.removeOnRetenoCustomPushReceivedListener() RetenoPlugin.setNotificationActionHandler() ``` Platform notes: - `setOnRetenoPushDismissedListener()` / `removeOnRetenoPushDismissedListener()` are Android-specific; - `setOnRetenoCustomPushReceivedListener()` / `removeOnRetenoCustomPushReceivedListener()` are Android-specific. Recommended mapping: - cold-start / initial notification: - `RetenoPlugin.getInitialNotification()`; - foreground Reteno push: - `RetenoPlugin.setOnRetenoPushReceivedListener(...)`; - app-side notification click handling: - `RetenoPlugin.setOnRetenoNotificationClickedListener(...)`; - Android notification dismissal: - `RetenoPlugin.setOnRetenoPushDismissedListener(...)`; - Android custom push payload: - `RetenoPlugin.setOnRetenoCustomPushReceivedListener(...)`; - action buttons: - `RetenoPlugin.setNotificationActionHandler(...)`. Remove listeners when the application lifecycle requires cleanup. Do not claim foreground payload handling, cold-start notification retrieval, app-side click routing, custom push data, dismissal handling, or action-button handling was validated without identifying the API used. Verify method availability against the installed plugin version before implementation. ### 1. Push registration After SDK integration, verify that the app registers for remote notifications through the selected Cordova / native setup. Expected result: - `deviceready` fires; - SDK initializes; - notification permission can be requested; - push token is obtained; - push token is passed to Reteno through the selected platform route; - Reteno contact has `mobilePushToken`; - token type matches the selected Reteno app configuration. ### 2. Android push handling For Android, expected token type is: ```text FCM ``` Verify: - Android Firebase setup is correct; - `google-services.json` matches the effective Android application ID; - Google Services Gradle plugin is applied; - `cordova-android` version is `12.0.0` or higher; - notification permission is handled on Android 13+; - Firebasex does not block Reteno FCM callbacks; - notification is shown on-device; - `DELIVERED` and `CLICKED` evidence can be verified. ### 3. iOS push handling For iOS, expected token type is: ```text APNs ``` or: ```text FCM ``` depending on selected push route and token handling mode. Verify: - deployment target is `15.0` or higher; - `IOS_DEVICE_TOKEN_HANDLING_MODE` is selected and documented; - App Groups are configured; - Notification Service Extension is configured; - Notification Content Extension is configured if rich push UI is enabled; - Firebase/APNs route is configured correctly; - `RetenoPlugin.setDeviceToken(token)` is called when the app uses external token handling; - token is assigned to the Reteno contact; - `DELIVERED` and `CLICKED` evidence can be verified. ### 4. Push opening and `CLICKED` After `DELIVERED` status is available, verify that push interaction is tracked. The test push notification must be opened in the selected test environment. If you can interact with the device/simulator/emulator: 1. Open the delivered notification. 2. Confirm that the app opens. 3. Continue Reteno MCP validation. 4. Verify `CLICKED`. If you cannot interact with the environment: 1. Ask the developer or QA engineer to open the delivered test push manually. 2. Wait for confirmation. 3. Continue Reteno MCP validation. 4. Verify `CLICKED`. Do not treat inability to tap a notification automatically as an SDK integration failure. Document it as a local automation limitation or manual fallback. ### 5. Deeplinks in push payloads Reteno can deliver deeplinks in push payloads. In Cordova apps, routing inside the WebView usually requires an app-level deeplink layer. Supported routing approaches may include: - custom URL scheme plugin; - Universal Links; - Android App Links; - Branch.io; - another app-level routing provider. Do not assume Reteno push delivery automatically navigates to the correct WebView route. Expected result: - Reteno delivers the push payload; - the app-level deeplink router opens the correct route; - foreground, background, and terminated-state behavior are validated separately. Do not treat successful warm-start behavior as proof that cold-start handling works. ## Cordova user identification Use this section when user identification or `externalCustomerId` validation is part of the current integration task. Do not validate `externalCustomerId` unless this check is requested or the integration modifies user identification behavior. ### 1. Anonymous contact Before login or registration, SDK initialization should create or update an anonymous contact when the app runs. Expected result: - contact exists in Reteno; - `contactId` is available; - `deviceId` is available when this data can be retrieved; - platform / OS information is available; - `externalCustomerId` is not required at this stage; - `mobilePushToken` may be assigned if push permission and token setup are complete. ### 2. Identified user When the user logs in, signs up, or updates their profile, identify the user through Cordova user information API. Use: ```js RetenoPlugin.setUserAttributes({ externalUserId: 'USER_ID', user: {} }) .then(() => { console.log('setUserAttributes: OK'); }) .catch((err) => { console.error('setUserAttributes: ERROR', err); }); ``` Use a stable backend user ID as `externalUserId` whenever available. Do not use unstable identifiers such as: - device ID; - mobile push token; - temporary session ID; - random UUID generated on the device. The value may be numeric or non-numeric, as long as it is stable and approved by the product/backend team. If the application uses email as `externalUserId`, document it as the selected product identifier, not as an SDK limitation. Expected result: - before login or registration, the contact is anonymous; - after login or registration, `externalUserId` is sent through `RetenoPlugin.setUserAttributes(...)`; - Reteno-side `externalCustomerId` is assigned to the same contact/device; - `mobilePushToken` remains assigned after identification. ### 3. User attributes If user attribute validation is part of the current integration task, use `RetenoPlugin.setUserAttributes(...)` with the approved user attributes. Example structure: ```js RetenoPlugin.setUserAttributes({ externalUserId: 'USER_ID', user: { userAttributes: { email: 'user@example.com', firstName: 'John', lastName: 'Doe', languageCode: 'en', timeZone: 'Europe/Kyiv', marketId: 'market_1' }, subscriptionKeys: ['news'], groupNamesInclude: ['vip'], groupNamesExclude: ['inactive'] } }); ``` Use valid formats: - `languageCode`: RFC 5646 format; - `timeZone`: TZ database format. Do not send real personal data in test integrations unless the developer explicitly confirms that the test account is approved. ### 4. Anonymous user attributes If anonymous user attributes are part of the current integration task, use: ```js RetenoPlugin.setAnonymousUserAttributes({ firstName: 'Guest', lastName: 'User', languageCode: 'en', timeZone: 'Europe/Kyiv' }); ``` Do not use anonymous attributes for email or phone. Use identified user flow with `externalUserId` when email or phone is involved. ### 5. Multi-account user attributes If the app uses multiple Reteno accounts, use the official multi-account user attribute method only when the developer confirms the account suffix and expected account mapping. Document: - account suffix; - external user ID; - which Reteno account received the update; - whether the update was verified. ### 6. Market ID If `marketId` is part of the current integration task, verify that the installed Cordova plugin and native SDK versions support it. `marketId` value should contain only: - Latin letters; - digits; - hyphens; - underscores. Maximum length: ```text 64 characters ``` To clear an existing `marketId`, pass an empty string. To keep the existing value unchanged, omit `marketId`. ## MCP Capability Discovery and Validation After applying Cordova SDK integration changes, validate the integration through Reteno MCP. Do not mark the integration as complete until all required validation checks pass or a blocker is clearly documented. ### MCP capability discovery Before using Reteno MCP for validation, discover which capabilities are actually available and authorized in the current agent environment. Verify that Reteno MCP is connected in the same environment where the AI coding agent runs. For Cordova core mobile push validation, possible capabilities may include: - finding a contact by `contactId`, if available; - finding a contact by `deviceId`, if available; - displaying the assigned `mobilePushToken`; - identifying token type: `FCM` or `APNs`; - creating or selecting a test push notification; - sending a test push notification to one approved test contact; - checking `DELIVERED` status; - checking `CLICKED` status after the push notification is opened. Do not assume that all MCP capabilities are available. If a required MCP capability is unavailable, use an approved manual fallback, Reteno UI, backend data, SDK logs, device logs, redacted network logs, or mark the step as `blocked`, `manual fallback required`, or `missing MCP capability`. Do not mark the integration as complete if a required validation step could not be verified. ### Reteno MCP and local automation are separate Reteno MCP validates Reteno-side data and statuses. Reteno MCP is used for: - contact lookup; - `mobilePushToken` verification; - token type validation; - test push creation and sending when the capability is available and approved; - `DELIVERED` / `CLICKED` status checks when the capability is available; - feature-specific validation when the required MCP capabilities are available. Local device, simulator, emulator, Cordova CLI, Android Studio, Xcode, Gradle, or CocoaPods tooling is used for runtime interaction: - building the app; - installing the app; - running the app; - confirming that `deviceready` fires; - granting notification permission; - opening the delivered test push notification; - completing login or registration steps; - tapping an In-App message button, if required. If local automation is unavailable, ask the developer or QA engineer to perform the runtime action manually and continue validation after confirmation. If Reteno MCP is unavailable or a required MCP capability cannot provide reliable evidence, use another approved Reteno-side or runtime evidence source when available. Accepted evidence may include: - Reteno UI; - backend data; - SDK logs; - device logs; - redacted network logs; - on-device API responses; - screenshots; - developer / QA confirmation. Do not report validation as blocked only because MCP itself is unavailable. Use `Passed with warnings` when all required validation results are independently verified through reliable fallback evidence. Use `Blocked` or `Partial` when a required result cannot be verified through MCP or any approved fallback evidence. ### Validation flow #### 1. Check selected Reteno mobile app configuration Verify that the selected Reteno mobile app matches the Cordova target platform. Expected configuration: - Cordova Android: `FCM`; - Cordova iOS with direct APNs: `APNs`; - Cordova iOS with Firebase / FCM: `FCM`. Ask the developer or admin to confirm: - selected Reteno mobile app; - target validation platform: Android, iOS, or both; - token type configured for the selected app: `FCM` or `APNs`; - Firebase / FCM setup, if `FCM` is used; - APNs sandbox / production setup, if direct APNs is used; - whether the selected Reteno app matches the selected test environment. If MCP cannot read app-level push configuration, ask the developer or admin to confirm it manually. Do not change app-level Reteno configuration automatically unless this action is explicitly supported and confirmed by the developer or admin. #### 2. Create or initialize an anonymous contact Before login or registration, initialize the SDK and create an anonymous contact. At this stage, the contact must be anonymous. To verify that the contact was created, use Reteno MCP, backend data, SDK logs, device logs, or Reteno UI. Expected result: - `contactId` is available through Reteno-side evidence, if retrievable; - `deviceId` is available through Reteno-side evidence, if retrievable; - platform / OS information is available; - `externalCustomerId` is not required at this stage; - `mobilePushToken` may or may not be available, depending on push permission and token setup. Use `contactId` as the primary identifier when it is available. If Reteno MCP supports `deviceId` lookup, also verify that the same contact can be found by `deviceId`. If `contactId` or `deviceId` is unavailable, correlate the anonymous contact using available evidence: - redacted `mobilePushToken`; - token type; - platform; - app version / build version; - OS version; - device model, if available; - Reteno contact creation or update timestamp; - SDK logs; - device logs; - Reteno UI; - backend data; - test push message ID, name, or `messageTag`. Do not include full push tokens in the final report. #### Feature-specific validation: custom event Use this check only when the current integration task includes custom event validation or explicitly asks to validate a custom event. Do not hardcode a required event name. Ask the developer to confirm the event name. When custom event validation is part of the current integration task, use the required `logEvent` payload shape: ```js RetenoPlugin.logEvent({ eventName: 'EVENT_NAME', date: new Date().toISOString(), parameters: [ { name: 'parameterName', value: 'parameterValue' } ] }) .then(() => console.log('logEvent: OK')) .catch((err) => console.error('logEvent: ERROR', err)); ``` Required: - `eventName`. Optional: - `date` in ISO-8601 format; - `parameters`; - `forcePush`. If `date` is omitted, the current time is used on Android API 26+. Do not require `date` when the selected Cordova SDK API allows it to be omitted. Use `parameters` only when event parameters are part of the current validation task. Use `forcePush` only when the integration explicitly requires immediate SDK data synchronization. After logging the event, call: ```js RetenoPlugin.forcePushData() .then(() => console.log('forcePushData: OK')) .catch((err) => console.error('forcePushData: ERROR', err)); ``` before immediate backend, Reteno UI, or MCP validation. Expected result: - event is sent from the Cordova app; - queued SDK data is flushed when immediate validation is required; - event appears in Reteno through MCP, Reteno UI, backend data, SDK logs, device logs, or another approved evidence source; - event is correlated with the correct contact using available evidence. If the event cannot be verified immediately and `RetenoPlugin.forcePushData()` was not called, do not mark validation as failed until queued SDK data behavior is considered. #### Feature-specific validation: screen tracking Use this check only when the current integration task includes screen tracking. In Cordova apps, native automatic screen tracking is usually not meaningful because the UI runs inside a single WebView. Use manual screen tracking from the app router when screen analytics are part of the current integration task. Use: ```js RetenoPlugin.logScreenView('ScreenName') .then(() => console.log('logScreenView: OK')) .catch((err) => console.error('logScreenView: ERROR', err)); ``` Expected result: - screen name is logged from the actual JavaScript route; - event is assigned to the correct contact; - event can be verified through Reteno MCP, Reteno UI, backend data, SDK logs, or device logs. #### 7. Validate feature-specific flows Run feature-specific validation only when the current integration task includes the related feature. Feature-specific validation may include: - custom events; - screen tracking; - App Lifecycle Events; - Ecommerce; - Recommendations; - App Inbox; - In-App messages; - mobile-push + In-App; - user identification / `externalCustomerId`; - deeplinks; - custom push data; - action buttons; - Android notification grouping; - Android notification channel creation or updates; - App Inbox `OPENED` / `UNOPENED` status, only when App Inbox validation is requested. Use the matching official Cordova feature guide for every feature-specific validation path. Relevant documentation includes: - Ecommerce → `Ecommerce/README.md`; - Recommendations → `Recommendations/README.md`; - App Inbox → `AppInbox/README.md`; - App Lifecycle Events → `AppLifeCycleEvents/README.md`; - push handling, notification grouping, notification channels, custom push data, and action buttons → official Cordova Push Notification documentation. Do not infer feature behavior from another platform's SDK. If a requested feature is documented by the installed Cordova plugin but is not covered by this runbook, locate the matching official Cordova guide before implementing or validating it. ## Local Device, Simulator, Emulator, and Cordova Automation Reteno MCP and local runtime automation are separate. Reteno MCP validates Reteno-side data and statuses. Local runtime automation is used to build, install, launch, and interact with the Cordova application. ### Supported local automation methods For Cordova validation, local automation may include: - `mobile-mcp`; - `adb`; - `uiautomator`; - Android Studio tools; - Xcode tools; - Cordova CLI; - Gradle; - CocoaPods; - simulator controls; - emulator controls; - manual developer / QA interaction. If `mobile-mcp` is unavailable but another approved local automation method works, such as `adb`, `uiautomator`, Cordova CLI, Android Studio, Xcode, or manual interaction, use it and document the method in the final report. This is not a Cordova SDK integration failure. ### Cordova native bridge check Before runtime validation, verify that the Cordova native bridge is available. Expected result: - app launches; - WebView loads; - `deviceready` fires; - `RetenoPlugin` is available in JavaScript; - `RetenoPlugin.init(...)` is called after `deviceready`. If `deviceready` does not fire: - do not continue SDK validation; - inspect app startup and Cordova plugin loading; - ask the developer for runtime logs; - report runtime validation as blocked. ### Android automation For Android validation, you may use: - `cordova build android`; - `cordova run android`; - Android emulator; - physical Android device; - `adb`; - `uiautomator`; - Android Studio tools; - manual developer / QA interaction. Runtime actions may include: - installing the app; - launching the app; - confirming `deviceready`; - granting notification permission; - confirming Android 13+ permission behavior; - opening the delivered push notification; - confirming app open / navigation after notification tap; - collecting device logs. If you cannot open the delivered push automatically, ask the developer or QA engineer to open it manually and continue Reteno MCP validation after confirmation. ### iOS automation For iOS validation, you may use: - `cordova build ios`; - `cordova run ios`; - Xcode; - CocoaPods; - iOS simulator, if supported and confirmed by the developer; - physical iOS device; - manual developer / QA interaction. Runtime actions may include: - installing the app; - launching the app; - confirming `deviceready`; - granting push notification permission; - opening the delivered push notification; - confirming app open / navigation after notification tap; - collecting device logs. For push validation, physical iOS device is the safest acceptance environment unless the developer confirms that the selected simulator and Xcode runtime support remote notifications and token registration. If the selected iOS simulator cannot obtain a push token, use it only for build and launch validation and report end-to-end push validation as blocked. ### Cordova platform commands Cordova platform commands can rewrite native platform folders. Do not run these commands without explicit developer approval: ```bash cordova prepare cordova clean cordova platform rm android cordova platform add android cordova platform rm ios cordova platform add ios ``` If a command is required, document: - why it is required; - which platform it affects; - whether `platforms/` folders are committed; - whether manual native changes may be overwritten; - whether the developer approved the action. ### Manual fallback Use manual fallback when: - local automation is unavailable; - GUI interaction is required; - push notification must be opened manually; - login or registration is required; - In-App message must be clicked manually; - Cordova platform regeneration requires approval; - signing, provisioning, Apple Developer account access, or Firebase dashboard access is required; - simulator/emulator/device access is unavailable. When manual fallback is used, the final report must document: - what action was requested; - who completed the action; - when it was completed, if known; - what evidence was provided; - which validation step resumed after the manual action. ## Validation Requirements You must validate every Reteno SDK feature that it integrates, modifies, or is explicitly asked to verify. Do not treat feature-specific validation as optional when the feature is part of the current integration task. ### Core mobile push validation When mobile push integration is included, the following checks are required: - SDK initialization after `deviceready`; - contact creation; - notification permission request; - `mobilePushToken` assignment; - token type validation; - test push sending; - `DELIVERED` status; - push notification opening; - `CLICKED` status; - final report. Do not mark the integration as complete until core mobile push validation passes or a blocker is clearly documented. For Cordova core mobile push validation, the required interaction statuses are: ```text DELIVERED CLICKED ``` Reteno backend history or activity APIs may expose additional interaction records or statuses during the same message lifecycle. If a status such as: ```text READ ``` appears in backend or MCP evidence, treat it only as auxiliary evidence unless the current official Cordova SDK documentation explicitly defines it as a required status for the selected feature. Do not add `READ` to the Cordova core mobile push success criteria. Do not replace `CLICKED` validation with `READ`. App Inbox status validation remains separate and uses its own documented states, such as: ```text OPENED UNOPENED ``` ### Platform-specific token expectations Expected token type depends on platform and selected Reteno app configuration: | Platform | Expected token type | |---|---| | Cordova Android | `FCM` | | Cordova iOS with direct APNs | `APNs` | | Cordova iOS with Firebase / FCM | `FCM` | The token assigned to the contact must match the token type configured for the selected Reteno mobile app. ### Android validation success criteria For Cordova Android validation, success requires: - Cordova app root detected; - Cordova project type detected; - `cordova-plugin-reteno` installed or confirmed; - `cordova-android` version is `12.0.0` or higher; - `google-services.json` present and matching the effective Android application ID; - Google Services Gradle plugin applied; - Android 13+ notification permission flow configured when required; - Firebasex conflict checked; - app builds and runs on the selected Android test environment; - `deviceready` fires; - SDK initializes after `deviceready`; - contact is created or found; - `mobilePushToken` is assigned; - token type is `FCM`; - test push is sent to one approved test contact when the capability is available and approved; - delivery evidence is verified; - click / interaction evidence is verified after opening the notification; - final report documents any fallback evidence or warnings. ### iOS validation success criteria For Cordova iOS validation, success requires: - Cordova app root detected; - Cordova project type detected; - `cordova-plugin-reteno` installed or confirmed; - `cordova-ios` version is `8.0.0` or higher; - iOS deployment target is `15.0` or higher; - Xcode `15.0` or higher is available; - Swift `5.7` or higher is supported; - selected `IOS_DEVICE_TOKEN_HANDLING_MODE` is documented; - Push Notifications capability configured when required; - App Group configured in the required format; - Notification Service Extension configured when required; - extension Podfile includes Reteno for extension targets when required; - app builds and runs on the selected iOS test environment; - `deviceready` fires; - SDK initializes after `deviceready`; - contact is created or found; - `mobilePushToken` is assigned; - token type is `APNs` or `FCM`, depending on selected route; - test push is sent to one approved test contact when the capability is available and approved; - delivery evidence is verified; - click / interaction evidence is verified after opening the notification; - final report documents any fallback evidence or warnings. ### Feature-specific validation Run feature-specific validation only when the feature is part of the current integration task. Feature-specific validation may include: - custom events; - user identification / `externalCustomerId`; - user attributes; - anonymous user attributes; - multi-account user attributes; - screen tracking; - App Lifecycle Events; - Ecommerce; - Recommendations; - App Inbox; - deeplinks; - custom push data; - In-App messages; - mobile-push + In-App; - action buttons; - Android notification grouping; - Android notification channel creation or updates; - App Inbox `OPENED` / `UNOPENED` status, when App Inbox validation is requested. If a feature was not part of the current integration task, report it as: ```text not requested for this integration ``` If a feature was part of the current integration task but could not be validated, report it as one of the following: ```text blocked manual fallback required missing MCP capability unavailable test environment unavailable Reteno UI / admin setup ``` ### Evidence rules The final report must state how each result was verified. Valid evidence may include: - Reteno MCP result; - Reteno UI confirmation; - backend data; - SDK logs; - device logs; - redacted network logs; - on-device API response; - screenshot or screen recording; - developer / QA confirmation. Evidence collected on one platform must not be treated as evidence for another platform. Android result does not validate iOS. iOS result does not validate Android. ### Complete vs Partial report Use `Complete` only when all required validation checks for the current integration task pass. Use `Partial` when any required build, run, runtime interaction, Reteno-side validation, contact lookup, contact correlation, token verification, test push, `DELIVERED`, `CLICKED`, or feature-specific validation step was skipped, blocked, or not verified. Use `Passed with warnings` only when required validation passes but non-blocking warnings remain. Use `Blocked` when the integration cannot continue because of missing credentials, missing Reteno MCP, unavailable test environment, unavailable Firebase/APNs setup, Cordova platform regeneration approval, Firebasex conflict, signing issues, or required manual action that has not been completed. Use `Failed` when the integration was attempted and a required validation check failed with evidence. Do not mark a validation step as passed only because code was added. ## Cordova Troubleshooting If validation fails, identify the failed step and troubleshoot before escalating. Do not stop immediately after a failed validation check. Check the likely cause, document the result, retry safe fixes, and continue with the remaining validation steps where possible. ### Cordova project type is unclear If the Cordova project type cannot be classified, inspect: - `config.xml`; - `package.json`; - `www/`; - `platforms/`; - `plugins/`; - `hooks/`; - Ionic config, if present; - Capacitor config, if present; - Cordova scripts; - installed plugin list; - repository instructions. Do not run Cordova platform commands until the project type and platform ownership are confirmed. If still unclear, ask the developer whether the project is: - pure Cordova app; - Ionic app using Cordova runtime; - Ionic app using Capacitor runtime; - Capacitor app using Cordova plugin compatibility layer; - non-Cordova project. ### `platforms/` ownership is unclear If `platforms/` folders exist, determine whether they are generated artifacts or committed source. If generated: - prefer changes in `config.xml`, plugin variables, hooks, or source files; - avoid direct manual edits under `platforms/`; - run `cordova prepare` only if approved. If committed and manually maintained: - inspect native changes carefully; - preserve existing native configuration; - ask before regenerating platforms. Do not run `cordova platform rm/add` or `cordova prepare` until platform ownership is clear. ### Plugin variable changed but native config did not update If `SDK_ACCESS_KEY` or `IOS_DEVICE_TOKEN_HANDLING_MODE` was changed but native config did not update: - confirm whether Cordova plugin variables were changed after plugin installation; - confirm whether `cordova prepare` is required; - confirm whether plugin reinstall is required; - ask for developer approval before running platform regeneration or plugin reinstall. Do not repeatedly edit generated files if the actual issue is stale Cordova platform output. ### `deviceready` does not fire If `deviceready` does not fire: - SDK initialization cannot be validated; - Cordova native bridge may not be ready; - plugins may not be loaded; - app startup may be broken. Check: - app entry point; - `www/` source files; - script loading order; - Cordova script inclusion; - platform build output; - runtime console logs; - plugin installation state. Do not initialize Reteno before `deviceready`. ### `RetenoPlugin` is undefined If `RetenoPlugin` is undefined: - verify `cordova-plugin-reteno` is installed; - verify `cordova prepare` was run when required and approved; - verify the app is running as a Cordova build, not a plain browser/WebView preview; - verify plugin JS was injected; - verify `deviceready` fired before plugin usage. Do not continue Reteno validation until the plugin bridge is available. ### SDK initialization is missing or duplicated If SDK initialization does not work, check: - whether `RetenoPlugin.init(...)` is called; - whether it is called after `deviceready`; - whether it is called only once; - whether SDK access key is available; - whether plugin variable or `config.xml` is correct; - whether initialization is delayed by app startup, authentication, or routing logic. Do not duplicate `RetenoPlugin.init(...)`. Do not initialize Reteno before Cordova native bridge is ready. ### Android build fails If Android build fails, check: - Cordova CLI version; - `cordova-android` version; - `cordova-plugin-reteno` version; - Android Gradle plugin version; - Gradle files; - Java / Kotlin compatibility; - `google-services.json`; - Google Services Gradle plugin; - Firebase dependencies; - Android package name / `applicationId`; - duplicate Firebase Messaging service definitions; - `cordova-plugin-firebasex`; - generated native Android project. Do not repeat the same failed action without a new hypothesis. If the issue requires local environment access or cannot be resolved safely by the agent, ask the developer to run the app through Cordova CLI, Android Studio, or Gradle and provide: - exact error message; - Cordova CLI logs; - Gradle logs; - emulator or device details; - reproduction steps. ### `cordova-android` is below 12.0.0 If `cordova-android` is below `12.0.0`: - do not proceed as if Android setup is valid; - report the platform version blocker; - ask the developer whether upgrading `cordova-android` is approved. Do not upgrade `cordova-android` automatically. Treat the upgrade as a product/build compatibility decision. ### Android `mobilePushToken` is missing If the Android contact exists but `mobilePushToken` is missing, check: - `deviceready` fired; - `RetenoPlugin.init(...)` executed successfully; - `cordova-android` version is `12.0.0` or higher; - source `google-services.json` exists in one of the supported project locations: - project root; - `resources/google-services.json`; - `resources/android/google-services.json`; - source `google-services.json` matches the effective Android application ID; - generated `platforms/android/app/google-services.json` exists after the approved prepare/build flow; - generated Firebase configuration matches the source configuration; - Google Services Gradle plugin is applied; - Reteno app is configured for Android / `FCM`; - Firebase server-side configuration is completed in Reteno; - notification permission is granted on Android 13+; - `cordova-plugin-firebasex` is not blocking Reteno FCM callbacks; - app was launched after integration changes; - network is available; - token assignment has had time to sync. If the generated file is missing or incorrect, fix the source configuration. Do not manually patch `platforms/android/app/google-services.json` when the Android platform folder is generated. ### Firebasex conflict If `cordova-plugin-firebasex` is installed and Reteno FCM callbacks do not work: - inspect AndroidManifest merged services; - inspect generated native Android project; - check whether Firebasex registers `FirebaseMessagingService`; - check whether Reteno callbacks receive FCM token; - ask an Android/Cordova SME to confirm the correct integration path. Do not remove Firebasex automatically. If Firebasex is required by the app, preserve it and document the limitation or required follow-up. ### iOS build fails If iOS build fails, check: - Cordova CLI version; - `cordova-ios` version; - whether `cordova-ios` is `8.0.0` or higher; - `cordova-plugin-reteno` version; - iOS deployment target; - Xcode version; - Swift version; - `config.xml`; - `platforms/ios/Podfile`; - CocoaPods installation; - `pod install`; - `.xcworkspace`; - Notification Service Extension; - Notification Content Extension; - App Groups; - signing and provisioning; - `GoogleService-Info.plist`, if Firebase / FCM is used; - APNs / FCM setup. If `cordova-ios` is lower than `8.0.0`, treat the platform version as a compatibility blocker. Do not troubleshoot Reteno native iOS setup further until the Cordova iOS engine requirement is satisfied or the developer approves an upgrade. Do not repeat the same failed action without a new hypothesis. If the issue requires local environment access or cannot be resolved safely by the agent, ask the developer to run the app through Cordova CLI, Xcode, or CocoaPods and provide: - exact error message; - Xcode logs; - CocoaPods logs; - simulator or device details; - reproduction steps. ### CocoaPods cannot resolve Reteno Before changing pod versions, verify: - `cordova-ios` is `8.0.0` or higher; - the extension target Reteno pod version matches the `` value in the installed `plugin.xml`; - the iOS deployment target satisfies the selected Reteno SDK requirements. If CocoaPods cannot find compatible versions for pod `Reteno`: - run `pod install --repo-update` only when developer approves; - run it from `platforms/ios`; - or ask the developer to run `cordova build ios -- --repo-update` when appropriate. If CocoaPods requires a higher minimum deployment target: - confirm current deployment target; - ask developer to approve iOS `15.0+`; - update `config.xml` only after approval. ### iOS `mobilePushToken` is missing If the iOS contact exists but `mobilePushToken` is missing, check: - `deviceready` fired; - `RetenoPlugin.init(...)` executed successfully; - iOS deployment target is `15.0` or higher; - selected `IOS_DEVICE_TOKEN_HANDLING_MODE`; - push permission is granted; - App Group is configured; - Notification Service Extension is configured; - extension Podfile includes Reteno when required; - Firebase / FCM setup is correct, if iOS uses Firebase / FCM; - `GoogleService-Info.plist` is added to the app target, if Firebase / FCM is used; - `RetenoPlugin.setDeviceToken(token)` is called when another SDK/plugin owns token retrieval; - APNs sandbox / production route is correct; - selected Reteno app token type matches the selected route. ### iOS `DELIVERED` is missing If iOS test push is sent but `DELIVERED` is missing, check: - whether selected route is FCM or direct APNs; - whether token type matches selected Reteno app; - whether APNs sandbox / production routing is correct; - whether App Group name is exactly `group..reteno-local-storage`; - whether App Group is applied to both main app and Notification Service Extension; - whether Notification Service Extension builds and runs; - whether extension target has the required Reteno pod; - whether Firebase APNs credentials are valid, if Firebase / FCM is used; - whether `RetenoPlugin.setDeviceToken(token)` is required and called. Do not assume SDK integration is wrong until token routing and push-provider configuration are confirmed. ### `CLICKED` is missing If `DELIVERED` is available but `CLICKED` is missing, check: - delivered notification was actually opened; - agent or developer opened the correct notification; - app opened after notification interaction; - Cordova WebView was resumed; - custom notification response handler is configured only when required; - app-level routing did not swallow the interaction; - terminated-state handling is tested separately from background state; - Reteno MCP can retrieve click status; - fallback evidence exists through SDK logs, device logs, Reteno UI, or backend data. If you cannot open the notification automatically, request manual opening and continue validation after confirmation. ### Deeplink or custom push data does not work If deeplink or custom push data validation is part of the current integration task, test separately: - foreground state; - background state; - terminated state; - custom URL scheme; - Universal Link or Android App Link; - Branch.io, if used; - actual WebView route; - actual destination screen. Check: - Cordova deeplink plugin; - app router; - WebView navigation; - Reteno push payload; - custom push payload callback; - duplicate navigation handling. Do not treat successful warm-start behavior as proof that cold-start handling works. ### In-App message does not appear If In-App message validation is part of the current integration task and the message does not appear, check: - SDK is initialized; - `deviceready` fired; - contact exists; - target contact is eligible; - segment rules match; - frequency limits; - trigger event or app-open trigger; - In-App message is active and published in the selected non-production environment; - selected Reteno app/environment is correct; - MCP capability exists or Reteno UI fallback is available; - app session is active; - logs show In-App fetch/display evidence. Do not publish or modify In-App messages without explicit developer or admin approval. ### Screen tracking does not work In Cordova apps, native automatic screen tracking is usually not meaningful because the UI runs inside a single WebView. Use manual screen tracking from the app router when screen analytics are part of the current integration task. Use: ```js RetenoPlugin.logScreenView('ScreenName'); ``` Expected result: - screen name is logged from the actual JavaScript route; - event is assigned to the correct contact; - event can be verified through Reteno MCP, Reteno UI, backend data, SDK logs, or device logs. ### Reteno MCP status lookup is unavailable, empty, stale, or returns an error If an MCP status or activity capability is unavailable, returns empty results, returns stale results, or returns an error, do not assume validation failed immediately. First determine whether the problem is: - missing MCP capability; - unsupported filter; - incorrect query shape; - stale backend data; - wrong contact; - wrong message; - wrong time range; - actual absence of the expected Reteno activity. If the discovered MCP capability includes contact activity lookup such as `get_contacts_activity_v2`, and filtering by `mobPushToken` returns no rows even though the token/contact is independently verified, retry with a broader correlation strategy when the capability supports it. For mobile push activity, this may include: - `mediaType: "mobilepush"`; - a narrow date/time range covering the current validation run; - contact identifiers when supported; - message ID; - `messageTag`; - interaction/request identifier; - timestamps from device logs. Do not conclude: ```text No mobile push activity exists ``` only because a single `mobPushToken` filter returns an empty result. Correlate the broader MCP result with the current validation run. If MCP still cannot provide reliable evidence, use approved fallback evidence when available: - Reteno UI; - backend data; - SDK logs; - device logs; - on-device API responses; - redacted network logs; - screenshots; - developer / QA confirmation. When fallback evidence is used: - document which MCP capability or filter was unavailable or unreliable; - document the alternate MCP query, if used; - document which fallback evidence was used; - correlate evidence only through available and verified identifiers; - do not include full push tokens or secrets; - report the result as `Passed with warnings` if required validation passed through reliable evidence; - report the result as `Blocked` or `Partial` if no reliable evidence is available. Treat an MCP query/filter limitation as an MCP validation limitation, not as a Reteno mobile SDK defect. ## Final Report Format Return a concise structured final report after every Cordova integration run. Do not use a long field-by-field report by default. Use the following: - Core report for every run; - Android section only if Android validation was part of the current integration task; - iOS section only if iOS validation was part of the current integration task; - Feature-specific section only for features requested in the current integration task. Validation result is mandatory. Reteno MCP is the preferred Reteno-side validation path, but MCP itself is not the validation result. If MCP is unavailable or a required MCP capability is missing, use reliable fallback evidence when available: - Reteno UI; - backend data; - SDK logs; - device logs; - redacted network logs; - on-device API response; - developer / QA confirmation. Do not mark validation as passed unless the result is verified through at least one reliable evidence source. ### Core report | Field | Result | |---|---| | Report type | Complete / Partial | | Overall status | Passed / Passed with warnings / Blocked / Failed | | Repository / project | | | Branch / commit | | | Initial worktree state | Clean / Dirty / Unknown | | Application root | | | Validation scaffold used | Yes / No | | Original template/source modified | Yes / No / Not applicable | | Cordova project type | Pure Cordova / Ionic Cordova / Capacitor compatibility / Unknown | | Target validation platform | Android / iOS / Both | | `cordova-plugin-reteno` version | | | Initialization result | Passed / Failed / Not run | | `deviceready` result | Fired / Not fired / Not run | | `RetenoPlugin` bridge available | Yes / No / Not run | | Build/run result | Passed / Failed / Not run | | Core push validation | Passed / Failed / Blocked / Not run | | Evidence sources | MCP / Reteno UI / backend / SDK logs / device logs / manual confirmation | | Sandbox configuration used | Yes / No | | Merge readiness | Ready / Not ready / Not applicable | | `platforms/` ownership | Committed source / Generated / Gitignored / Mixed | | Required native changes durable across regeneration | Yes / No / Not verified / Not applicable | | Native regeneration mechanism | config.xml / Cordova hook / local plugin / project script / manual reapply / other / not applicable | | Pre-existing or collateral compatibility fixes | None / Yes — see warnings | | Blockers | | | Warnings | | | Changed files | | | Recommended next steps | | ### Android section, if applicable Include this section only when Android validation was part of the current integration task. Report: - Android package name / application ID; - `cordova-android` version; - whether `cordova-android` is `12.0.0` or higher; - Firebase config source; - Firebase source-to-generated-copy mechanism: - Cordova plugin hook; - project hook; - manual; - other; - whether `google-services.json` exists and matches the effective Android application ID; - Google Services Gradle plugin status; - whether `cordova-plugin-firebasex` was detected; - Firebasex conflict result: - not detected; - detected and verified; - detected and blocked pending SME review; - Android 13+ notification permission result; - token type expected: `FCM`; - token type verified: `FCM` / other / not verified; - `mobilePushToken` result: present / missing / not verified; - test push result; - `DELIVERED` result; - `CLICKED` result; - Android-specific fallback evidence, if used. - MCP query/filter limitation encountered, if any; - alternate MCP query used, if any; - Android compatibility changes unrelated to Reteno, if any; - Android-specific collateral plugin changes, if any; ### iOS section, if applicable Include this section only when iOS validation was part of the current integration task. Report: - iOS bundle ID; - `cordova-ios` version; - whether `cordova-ios` is `8.0.0` or higher; - iOS deployment target; - whether iOS deployment target is `15.0` or higher; - selected push route: - direct APNs; - Firebase / FCM; - selected `IOS_DEVICE_TOKEN_HANDLING_MODE`: - `manual`; - `automatic`; - whether `RetenoPlugin.setDeviceToken(...)` was required; - whether `RetenoPlugin.setDeviceToken(...)` was implemented; - Firebase config source, if Firebase / FCM is used; - Firebase plist source-to-Xcode-target mechanism: - `config.xml` resource configuration; - Cordova hook; - project-owned local plugin; - generated/manual; - other; - whether `GoogleService-Info.plist` exists and matches the effective iOS bundle ID; - App Group name; - whether App Group uses the required format; - Notification Service Extension status; - Notification Content Extension status, if applicable; - extension Podfile Reteno pod status; - Notification Service Extension Reteno linkage result; - extension linker fix required: Yes / No; - extension linker fix mechanism, if applicable; - extension/native changes survive `cordova platform rm/add ios`: Yes / No / Not verified; - token type expected: `APNs` / `FCM`; - token type verified: `APNs` / `FCM` / other / not verified; - `mobilePushToken` result: present / missing / not verified; - test push result; - `DELIVERED` result; - `CLICKED` result; - iOS-specific fallback evidence, if used. - MCP query/filter limitation encountered, if any; - alternate MCP query used, if any; ### Feature-specific section, if applicable Include this section only for features requested in the current integration task. For each requested feature, report: ```markdown #### - Requested: Yes - Implemented: Yes / No / Not applicable - Validated: Passed / Failed / Blocked / Not run - Evidence source: - Blocker or warning: ``` Feature-specific checks may include: - custom event; - screen tracking; - user identification / `externalCustomerId`; - deeplink; - custom push data; - foreground push handling; - background push handling; - terminated-state push handling; - action buttons; - In-App message; - mobile-push + In-App flow. - App Lifecycle Events; - Ecommerce; - Recommendations; - App Inbox; - App Inbox `OPENED` / `UNOPENED` status; - Android notification grouping; - Android notification channel creation or updates. If a feature was not part of the current integration task, report it as: ```text not requested for this integration ``` Do not use: ```text MVP extended validation optional out of scope out of MVP scope included in scope selected validation scope ``` ### Report rules Use `Complete` only when all required validation checks for the current integration task pass. Use `Partial` when any required build, run, runtime interaction, Reteno-side validation, contact correlation, token verification, test push, `DELIVERED`, `CLICKED`, or requested feature-specific validation step was skipped, blocked, or not verified. Use `Passed` only when all required validation checks pass. Use `Passed with warnings` only when required validation passes but non-blocking warnings remain, such as: - manual fallback was used; - MCP was unavailable but reliable fallback evidence verified the result; - non-required feature validation was not requested; - sandbox configuration was used intentionally and documented. Use `Blocked` when the integration cannot continue because of missing credentials, missing Reteno access, unavailable test environment, unavailable Firebase/APNs setup, Cordova platform regeneration approval, Firebasex conflict, signing issue, or required manual action that has not been completed. Use `Failed` when the integration was attempted and a required validation check failed with evidence. Do not require `requestId` or any other implementation-specific MCP response field in the final report. Do not include secrets, SDK access keys, Firebase server credentials, APNs private keys, certificates, service account data, or full push token values in the final report. Use redacted values for sensitive identifiers when needed. If a secret was exposed in tool output, do not repeat the secret value in the final report. Report only: - what type of secret was exposed; - where it was exposed: logs, terminal output, tool output, screenshot, or prompt; - whether rotation is recommended; - which provider/dashboard should be used for rotation. Use: ```text Secret exposure detected: Yes Secret rotation recommended: Yes ``` Do not include the exposed value itself.