React Native AI-Assisted Integration

Purpose

This runbook helps an AI coding agent integrate the Reteno React Native SDK into an existing React Native application and validate that the integration works correctly.

The agent 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 React Native SDK into an existing React Native application.

Your goal is not only to update the code, but also to validate that the SDK integration works correctly across the JavaScript / TypeScript layer and the required native iOS / Android configuration.

Do not treat this as a native iOS or native Android integration by default.

Start with the React Native project structure and apply native iOS or Android changes only when the React Native SDK setup requires them.

Quick Start Prompt

Use this React Native runbook as your operating instruction.

Integrate the Reteno React Native SDK from scratch into the selected React Native application.

First inspect the project and detect the React Native project structure, package manager, app entry point, React Native version, existing Reteno usage, Firebase setup, FCM/APNs setup, native iOS/Android folders, and existing push notification logic.

Use the official Reteno React Native SDK Guide as the primary source of truth for React Native-specific setup.

Use the official React Native Android SDK Setup when the React Native integration requires Android-specific changes in the generated android/ folder.

Use the official React Native iOS SDK Setup when the React Native integration requires iOS-specific changes in the generated ios/ folder.

Use the official React Native Push Notification Guide for push notification handling, push actions, custom push data, token handling, and deeplinks.

Use the official React Native In-App Messages Guide when In-App validation is part of the current integration task.

Use the official React Native SDK Release Notes to check SDK versions, migration notes, compatibility issues, and known fixes.

Before applying React Native SDK changes, explicitly verify the React Native-specific critical setup decisions:

selected reteno-react-native-sdk version;
target validation platform:
- Android;
- iOS;
- both;
selected iOS push route:
- direct APNs;
- Firebase / FCM;
whether the selected Reteno mobile app is configured for the same token route:
- Android: FCM;
- iOS direct APNs: APNs;
- iOS Firebase / FCM: FCM;
whether an iOS Direct APNs attempt is valid for the selected Reteno mobile app;
whether iOS must pivot to Firebase / FCM because the selected Reteno mobile app is FCM-configured;
whether @react-native-firebase/app is required;
whether @react-native-firebase/messaging is required;
whether Firebase is auto-configured or must be initialized explicitly from JavaScript;
whether Firebase Messaging runs in the app target or inside a linked framework / SDK target;
whether duplicate Firebase registries may exist across app target and framework targets;
whether @react-native-firebase/messaging tries to use Swift Package Manager;
whether enabling use_frameworks! would be safe for the existing dependency graph;
whether $RNFirebaseDisableSPM = true is required to keep the project on CocoaPods/static linkage;
whether Firebase Swift pods require scoped modular headers;
whether global use_modular_headers! would break React Native pods;
whether iOS bundle ID was changed for sandbox validation;
whether embedded extensions still have bundle IDs prefixed by the host app bundle ID;
whether any extension must be excluded from a test build as sandbox-only;
whether the run is sandbox-only and not merge-ready;
whether production validation must be repeated with the real bundle ID, Firebase project, Reteno mobile app, and signing setup.

Do not ask for all inputs upfront. Ask only for information that cannot be detected from the codebase, Reteno MCP, or official Reteno documentation.

Before making code changes, complete the 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.

Preserve existing application logic. Do not overwrite React Native app startup, Firebase configuration, push notification handlers, deeplink handling, authentication flow, analytics logic, or existing native platform configuration.

Use the existing React Native project setup. Do not switch package managers, app architecture, Firebase setup, push provider, or SDK versions 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 keys, 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, or another supported test environment.

If runtime UI Interaction is required and you cannot perform it directly, use the manual fallback described in Appendix: Local Device and Simulator Automation. If local automation is unavailable, ask the developer or QA engineer to perform runtime actions manually and continue Reteno MCP validation after confirmation.

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 external access, credentials, signing, dashboard changes, GUI interaction, or manual device actions are required.

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, continue with MCP Capability Discovery and Validation.

Do not assume that Reteno MCP can send pushes, retrieve DELIVERED / CLICKED statuses, or manage In-App messages until the available and authorized MCP capabilities are discovered in the current agent environment.
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, 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 and the current customer application codebase for React Native 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 React Native project structure, package manager, app root, entry point, React Native version, architecture mode, existing Reteno usage, native `ios/` and `android/` folders, 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 React Native SDK Guide	Open Reteno React Native SDK	Use it as the primary source of truth for React Native SDK overview, supported versions, and base setup	Ask the user to provide the React Native SDK documentation page
React Native Android SDK Setup	Open React Native Android SDK Setup	Apply Android-specific setup required by the React Native SDK	Ask the developer to confirm Android setup requirements
React Native iOS SDK Setup	Open React Native iOS SDK Setup	Apply iOS-specific setup required by the React Native SDK	Ask the developer to confirm iOS setup requirements
React Native Push Notification Guide	Open React Native Push Notification	Configure or verify push notification handling, token handling, push actions, custom push data, and deeplinks	Ask the developer to confirm React Native push handling requirements
React Native In-App Messages Guide	Open React Native In-App Messages	Configure or verify In-App behavior when In-App validation is part of the current integration task	Ask the developer or admin to confirm In-App setup requirements
React Native SDK Release Notes	Open React Native SDK Release Notes	Check SDK versions, compatibility, migration notes, and known fixes	Ask the developer or platform owner to confirm the SDK version
Reteno MCP Server Reference	Open Reteno MCP Server	Understand Reteno MCP connection and validation capability discovery	Ask the developer to connect Reteno MCP or provide MCP setup guidance
Reteno `llms.txt`	Open Reteno `llms.txt`	Locate the latest Reteno documentation pages, SDK guides, and API references	Use direct documentation links or ask the user to provide the relevant Reteno documentation page

Agent Behaviour Rules

Follow these rules throughout the React Native SDK integration:

Inspect the project before making any code changes.
Detect the React Native project structure, package manager, JavaScript/TypeScript entry point, native iOS/Android folders, current SDK version, Firebase setup, push notification setup, and notification handlers from project files whenever possible.
Ask the user only for information that cannot be detected from the project, Reteno MCP, or official Reteno documentation.
Use the existing project setup. Do not switch package managers, app architecture, Firebase setup, push provider, or SDK versions unless the developer explicitly confirms this.
Treat React Native as the highest-level framework. Do not start with native iOS or Android setup unless the React Native runbook or official React Native SDK docs require native changes.
Preserve existing application logic.
Do not overwrite React Native app startup, Firebase configuration, push notification handlers, deeplink handling, authentication flow, analytics logic, or existing native platform configuration.
Do not hardcode secrets, credentials, SDK access keys, Firebase keys, APNs credentials, service account data, private keys, certificates, or other sensitive values in public files.
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/TypeScript code, native project configuration, dependency setup, or available and authorized MCP capabilities.
Do not change external app configuration, credentials, APNs/FCM setup, sandbox/production settings, Firebase project settings, or Reteno dashboard settings without explicit developer or admin confirmation.

Change-safety boundaries

Follow these change-safety rules throughout the React Native integration.

Native lifecycle preservation

Preserve all existing AppDelegate, Firebase, notification delegate, application lifecycle, and Android messaging behavior while applying the mandatory targeted changes required by the current official platform setup guide.

Before editing native files, inventory:

AppDelegate notification methods;
UNUserNotificationCenterDelegate;
Firebase swizzling configuration;
MessagingDelegate;
existing Notification Service Extensions;
Android Firebase Messaging services and manifest intent filters;
background or headless JavaScript handlers;
existing URL and deeplink handlers.

Do not remove or replace existing handlers unless the official guide and developer confirmation require it.

iOS push route preflight: APNs vs FCM

Before implementing or validating iOS push, confirm which token route the selected Reteno mobile app is configured for.

Supported routes:

direct APNs;
Firebase / FCM with APNs transport.

Do not attempt Direct APNs validation against a Reteno mobile app configured for FCM.

Do not attempt FCM validation against a Reteno mobile app configured only for APNs.

If Direct APNs is attempted and push never arrives, check the selected Reteno mobile app configuration before treating the SDK integration as broken.

If the selected Reteno mobile app is FCM-configured:

use the iOS Firebase / FCM route;
verify that Firebase obtains an FCM token;
verify that Reteno receives an FCM token, not an APNs token;
verify that the FCM token belongs to the same contact used for the test push.

Document in the final report:

attempted iOS push route;
final iOS push route;
why the route changed, if it changed;
selected Reteno mobile app;
token type expected;
token type verified.

Native dependency safeguards

Do not add CocoaPods or Gradle dependencies from memory, by analogy with another SDK, or from an older integration.

Before adding native dependencies:

check what is already provided through React Native autolinking;
inspect the SDK dependency graph;
follow the official platform setup guide matching the installed SDK version;
verify resolved native dependency versions after installation.

Do not use latest native dependency versions automatically.

Do not create duplicate native dependencies.

React Native Firebase dependency mode: SPM vs CocoaPods

When adding @react-native-firebase/app or @react-native-firebase/messaging on iOS, inspect the existing CocoaPods / Swift Package Manager setup before changing linkage.

Do not enable use_frameworks! globally only because React Native Firebase or Firebase Messaging suggests or requires Swift Package Manager support.

Before enabling use_frameworks!, check whether the app depends on native libraries that may break under project-wide dynamic framework linkage, such as:

WebRTC;
Google Sign-In;
Giphy;
existing React Native native modules;
custom static libraries;
SDK framework targets.

If enabling use_frameworks! is risky, ask the iOS / React Native SME whether to disable React Native Firebase SPM and keep the project on CocoaPods/static linkage.

When approved, use the project-supported React Native Firebase setting, for example:

$RNFirebaseDisableSPM = true

Document:

whether React Native Firebase tried to use SPM;
whether use_frameworks! was considered;
why it was not used, if rejected;
whether $RNFirebaseDisableSPM = true was used;
which linkage mode the project kept.

Scoped modular headers for Firebase Swift pods

Do not enable use_modular_headers! globally in a React Native iOS project unless an iOS / React Native SME explicitly confirms it is safe.

Global use_modular_headers! can break React Native pods and produce module redefinition errors.

If Firebase Swift pods require Clang module maps from non-modular transitive dependencies, scope modular headers only to the specific Firebase transitive pods that need them.

Possible examples may include:

pod 'GoogleUtilities', :modular_headers => true
pod 'GoogleDataTransport', :modular_headers => true
pod 'nanopb', :modular_headers => true

Use the versions resolved by the current Podfile.lock or the selected Firebase dependency graph.

Do not pin or bump these dependencies from memory.

Document:

which pods required modular headers;
whether modular headers were scoped or global;
whether React Native pods still build;
whether Podfile.lock changed;
whether SME review is required.

Explicit Firebase initialization from JavaScript

Do not assume @react-native-firebase/app auto-configures the default Firebase app in every React Native iOS architecture.

In projects with split native targets, framework targets, or custom app shells, auto-configuration may not fire where Firebase Messaging is used.

Before expecting an FCM token, verify that the JavaScript layer that calls Firebase Messaging can see a configured default Firebase app.

If Firebase auto-configuration does not happen, initialize Firebase explicitly from the same JavaScript / TypeScript layer that calls messaging APIs.

Example shape:

import { initializeApp, getApps } from '@react-native-firebase/app';
import messaging from '@react-native-firebase/messaging';

if (getApps().length === 0) {
  await initializeApp(firebaseConfig);
}

const token = await messaging().getToken();

Use the project’s approved Firebase client configuration source.

Do not hardcode Firebase server credentials.

Document:

whether Firebase auto-configured;
whether explicit initializeApp(...) was required;
where initialization happens;
whether getMessaging() / messaging().getToken() sees the default app;
whether Reteno receives the expected FCM token.

Android `minSdkVersion` safeguard

Detect and report the current minSdkVersion.

Compare it with the requirements of the selected SDK version.

Do not raise minSdkVersion without explicit developer approval.

Treat a minSdkVersion increase as a product compatibility decision.

If Reteno cannot be active on some supported application OS versions, report that limitation instead of silently dropping those users.

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, or signing configuration.

Run integration validation only in an external private test fork.

Use separate non-production application IDs, Firebase projects, Reteno environments, and signing configuration.

Sandbox Firebase / app identity validation path

The agent may use a sandbox Firebase / Reteno app configuration only when the developer explicitly approves this as a dry-run validation path.

This may require changing the Android applicationId or iOS bundle ID to match a preconfigured Firebase / Reteno mobile app.

If the agent changes Android applicationId or iOS bundle ID for sandbox validation:

document that this is an approved sandbox-only validation path;
do not report the branch as merge-ready or production-ready;
document the original Android applicationId or iOS bundle ID;
document the temporary sandbox Android applicationId or iOS bundle ID;
document which Firebase project was used;
document which Reteno mobile app was used;
document whether Firebase client config matches the temporary app identity;
document any app behavior that may break because of the app identity change;
do not treat unrelated product behavior broken by the app identity change as a Reteno SDK defect;
require repeated validation before production use with the real app identity, real Firebase project, real Reteno mobile app, real SDK 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.

Test-only native changes and merge readiness

Some React Native integrations may require native workarounds to complete a dry-run validation.

Examples:

excluding an embedded extension because its bundle ID no longer matches a sandbox host bundle ID;
disabling dormant Analytics / Crashlytics in a test build;
changing Firebase ownership between app target and framework target;
adding temporary diagnostic instrumentation;
adding defensive timeout logic around permission requests;
adding Firebase options workaround fields.

These changes may be valid for dry-run validation, but they are not automatically merge-ready.

For each test-only native change, document:

what changed;
why it was required;
whether it is related to Reteno or project setup;
whether the developer approved it;
whether it should be reverted;
what production setup should do instead.

If any test-only native change remains in the working tree, report:

Merge readiness: Not ready / needs native review

iOS embedded extension bundle ID check

If the iOS bundle ID is changed for sandbox validation, inspect all embedded extensions before building.

Apple requires each embedded extension bundle ID to be prefixed by the host app bundle ID.

Before excluding, modifying, or reconfiguring an embedded extension, document:

host app bundle ID;
extension bundle ID;
whether the extension bundle ID is prefixed by the host bundle ID;
whether the extension is required for the current validation run;
whether exclusion is test-only;
whether production follow-up is required;
whether a separate provisioning profile is required.

Do not silently remove, exclude, or detach an existing extension.

If an extension is excluded for sandbox validation, report:

sandbox-only / not merge-ready / production follow-up required

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, dashboard changes, GUI interaction, or manual device actions are required.

Record attempted fixes and the first actionable error.

Do not retry indefinitely.

React Native Project Detection

Use this runbook for React Native applications.

Use this React Native SDK flow when the project contains React Native-specific files or configuration, such as:

package.json with React Native dependencies;
metro.config.js;
index.js;
index.ts;
App.js;
App.tsx;
babel.config.js;
react-native.config.js;
native ios/ and android/ folders generated by React Native;
Podfile;
AndroidManifest.xml;
build.gradle;
build.gradle.kts;
Firebase configuration files;
google-services.json;
GoogleService-Info.plist.

Before making changes, detect:

React Native project structure;
package manager: npm, Yarn, pnpm, or another package manager;
React Native version;
JavaScript or TypeScript usage;
app entry point, usually index.js, index.ts, App.js, or App.tsx;
existing Reteno React Native SDK usage, if any;
existing reteno-react-native-sdk dependency in package.json;
current Reteno React Native SDK version, if installed;
Firebase / FCM setup;
native Android setup under android/;
native iOS setup under ios/;
existing push notification setup;
existing deeplink handling;
existing custom event tracking;
existing authentication or user identification flow;
existing In-App message setup, if any.

Do not use the native Android or native iOS runbook directly for React Native projects.

Apply native Android or iOS steps only when the React Native SDK setup requires native platform changes.

If the project appears to be Flutter, Expo, Cordova, Ionic, Unity, or native iOS/Android instead of React Native, stop and ask the developer to confirm which platform runbook should be used.

If Expo-related dependencies or configuration are present, use the Expo detection guard before deciding whether to continue with this React Native runbook or switch to the Expo runbook.

Expo detection guard

Do not select the Expo runbook merely because an expo dependency exists.

Distinguish between:

bare React Native;
bare React Native using Expo modules;
Expo prebuild / CNG with committed native folders;
Expo managed without committed native folders.

If the project is bare React Native with Expo modules, continue with the React Native runbook and apply Expo-specific checks only where the project setup requires them.

Running Expo prebuild or generating native folders is a material project change and requires explicit developer approval.

Package manager detection

Detect the package manager using this evidence order:

nearest application-level package.json#packageManager;
relevant lockfile;
workspace configuration;
repository instructions.

Do not switch package managers.

Do not generate another package manager's lockfile.

Locate the application package before installing dependencies in a monorepo.

Explicitly verify:

React Native autolinking;
CocoaPods resolution, if iOS validation is included;
Android dependency resolution, if Android validation is included.

Treat unresolved conflicting lockfiles as a blocker.

Do not declare npm, Yarn, or pnpm incompatible in advance.

Required Inputs

Ask only for information that cannot be detected from the project files, Reteno MCP, or official documentation.

Required inputs may include:

Reteno SDK access key handling method;
selected Reteno app/environment;
target validation platform: Android, iOS, or both;
Android applicationId, if Android validation is included and cannot be detected;
iOS bundle ID, if iOS validation is included and cannot be detected;
selected push route:
- Android: FCM;
- iOS: Direct APNs or FCM with APNs transport;
Firebase/APNs setup confirmation;
selected test environment;
feature-specific inputs only when the feature is part of the current integration task.

For detailed preparation, use the Developer Preparation Checklist.

Security rules

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 according to repository policy.

Server credentials include:

Firebase Admin service accounts;
APNs authentication keys and certificates;
private keys;
Reteno REST API credentials.

Server credentials must never be committed, printed, logged, pasted into prompts, or included in the final report.

If a Reteno SDK access key is required, ask the developer to provide it through the approved project configuration method.

If a required input is missing, explain:

what information is missing;
why it is required;
whether the integration can continue without it;
which validation steps will be blocked until the input is provided.

Secret handling during debugging

Do not print, grep, cat, log, or otherwise expose SDK access keys, Firebase server credentials, APNs credentials, private keys, certificates, service account data, or other secrets in tool output.

When checking that a local config file exists or is loaded correctly:

verify file presence without printing its contents;
verify variable names without printing secret values;
use redacted output only;
never include full key values in logs, screenshots, terminal output, prompts, or final reports.

Do not run broad commands that may expose secrets, such as cat <secret-config-file>, grep -R RETENO ., or grep -R API_KEY ., unless the command is scoped to show only filenames or redacted output.

If a secret is accidentally printed in the agent session output:

report the exposure immediately;
mark it as a security warning / action required;
recommend rotating the exposed key in Reteno or the relevant provider dashboard;
do not repeat or copy the exposed value in the final report.

Developer Preparation Checklist

Before starting React Native SDK integration, ask the developer to prepare or confirm the items below.

The agent 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.

If local device or simulator automation is unavailable, ask the developer or QA engineer to perform the required runtime action manually and continue after confirmation. See Appendix: Local Device and Simulator Automation.

1. Project access

The developer should provide or confirm:

access to the React Native project repository;
the correct branch for the integration run;
whether the run should be done on a temporary local branch;
whether there are local agent instructions, such as CLAUDE.md, Cursor rules, or similar files;
whether the project uses npm, Yarn, pnpm, or another package manager;
whether the project uses JavaScript or TypeScript;
whether the app should be validated on Android, iOS, or both.

2. Reteno setup

The developer or admin should prepare or confirm:

selected Reteno organization / workspace;
selected Reteno mobile app for Android, if Android validation is included;
selected Reteno mobile app for iOS, if iOS validation is included;
Reteno SDK access key or approved configuration method for providing it;
whether the selected Android app is configured for FCM;
whether the selected iOS app is configured for FCM or APNs;
whether the selected Reteno app matches the target package name / bundle ID and environment;
whether the signed-in Reteno account has access to the selected app/environment.

Do not paste SDK access keys, Firebase keys, APNs credentials, private keys, certificates, or service account data into public chats, public files, or committed source files.

3. Firebase / APNs setup

For Android validation, the developer should confirm:

Firebase / FCM is configured for the Android app;
the correct google-services.json is available;
the Android package name / applicationId matches the Firebase and Reteno configuration.

For iOS validation, the developer should confirm:

whether iOS push uses FCM or APNs;
the correct GoogleService-Info.plist is available, if iOS uses FCM;
APNs sandbox / production setup is correct, if iOS uses APNs;
Apple signing, capabilities, App Groups, and Notification Service Extension setup can be modified or confirmed when required;
the iOS bundle ID matches the Firebase / APNs / Reteno configuration.

3.1 Server-side Firebase / APNs preflight

For React Native Android validation, confirm:

Firebase application identity matches the effective Android applicationId and flavor;
the correct client configuration file is present;
the required Google Services integration is applied;
Reteno has the required Firebase server-side configuration.

For React Native iOS validation with FCM, confirm:

the client configuration matches the iOS bundle ID;
Firebase has valid APNs credentials;
Reteno uses the corresponding Firebase project;
APNs and FCM tokens are not mixed.

For direct APNs validation, confirm:

bundle ID;
Team ID;
sandbox or production environment;
Reteno-side APNs credentials.

Never place service-account files, APNs private keys, certificates, or other server credentials in the repository, logs, prompts, or final report.

4. Test environment

The developer should prepare one or more supported test environments:

Android emulator, if Android validation is included;
physical Android device, if emulator validation is unavailable or unreliable;
iOS simulator, if supported and confirmed by the developer;
physical iOS device, if simulator validation is unavailable or production-like validation is required.

iOS simulator and sandbox policy

A physical iOS device is the default acceptance environment.

An iOS simulator may be used only after confirming that its Xcode and runtime versions support remote notifications.

The application must successfully obtain a push token before the simulator is considered a push-validation environment.

Simulator and development builds use the APNs sandbox environment.

Verify that the selected Reteno application and push-provider configuration use the matching sandbox route.

Do not treat a production APNs route as compatible with a simulator or development token.

For FCM-based iOS integration, verify Firebase APNs configuration and the Firebase project configured in Reteno.

If token registration, sandbox routing, or provider compatibility cannot be confirmed, use the simulator only for build and launch validation.

Report the environment, token route, sandbox/production mode, and whether end-to-end delivery was observed.

The developer should also confirm:

the app can be built and run in the selected environment;
push notification permission can be granted;
the developer can manually open the test push notification if the agent cannot interact with the device, simulator, or emulator directly;
the developer can provide logs if build/run fails.

5. MCP and local automation tools

The developer should confirm whether Reteno MCP is connected in the same environment where the AI coding agent runs.

Reteno MCP is required for Reteno-side validation:

contact lookup;
mobilePushToken verification;
test push creation and sending;
DELIVERED / CLICKED status checks.

Local device, simulator, or emulator automation tooling is separate from Reteno MCP.

Local automation tooling is used for runtime interaction:

running the app;
granting notification permission;
opening the test push notification.

If local automation tooling is unavailable, the developer should be ready to perform these actions manually and confirm completion.

If Reteno MCP is unavailable, Reteno-side validation cannot be completed and must be reported as blocked or pending.

6. 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 build command used;
exact error message;
Metro logs, if relevant;
Android Gradle logs, if Android build fails;
Logcat output, if Android runtime fails;
Xcode logs, if iOS build or runtime fails;
simulator, emulator, or device details;
reproduction steps.

7. Feature-specific validation preparation

If the current integration task includes custom events, the developer should confirm:

a test custom event can be added to the React Native app code;
the event name testAiEvent can be used;
event validation is possible through Reteno MCP, Reteno UI, backend logs, or event logs.

If the current integration task includes In-App messages, the developer or admin should confirm:

whether an In-App message already exists or should be created;
existing In-App message name or ID, if an existing In-App should be used;
whether default In-App message creation is available in the selected Reteno account;
whether the developer/admin can create, configure, publish, or confirm the In-App message manually in Reteno UI.

If the current integration task includes externalCustomerId, the developer should confirm:

login or registration flow can be tested;
test credentials are available;
expected stable customer ID format is known.

8. Pre-flight result

Before code changes start, the agent should summarize the pre-flight status:

project access: ready / blocked;
SDK access key handling: ready / placeholder / missing;
Reteno MCP: connected / unavailable;
test environment: ready / unavailable;
Firebase / APNs setup: confirmed / needs confirmation;
manual actions required from developer;
validation steps that may be blocked.

If a required item is missing, continue only with the steps that are not blocked.

Do not mark the integration as complete until build/run and required Reteno MCP validation are completed or a blocker is clearly documented.

React Native SDK Integration Workflow

Follow this workflow for React Native SDK integration.

0. Prepare a safe working branch

Before making code changes, check the current Git branch and working tree state.

For evaluation, test, or temporary integration runs:

create and switch to a temporary local branch;
do not make temporary integration changes directly on main or master;
do not commit, push, or merge changes unless the developer explicitly asks for it.

If you cannot create or switch to a temporary branch, ask the developer to confirm how to proceed before modifying files.

Report the branch name and working tree state in the final report.

1. Inspect the project

Before making changes, inspect the React Native project.

Identify:

React Native project structure;
package manager: npm, Yarn, pnpm, or another package manager;
React Native version;
JavaScript or TypeScript usage;
app entry point, for example index.js, index.ts, App.js, or App.tsx;
existing Reteno React Native SDK usage, if any;
existing reteno-react-native-sdk dependency;
current Reteno React Native SDK version, if installed;
native Android setup under android/;
native iOS setup under ios/;
Firebase / FCM setup;
google-services.json;
GoogleService-Info.plist;
existing push notification setup;
existing notification handlers;
existing deeplink handling;
existing custom event tracking;
existing user identification or login flow;
existing In-App setup, if present;
files that may need to be updated.

Do not ask the developer for information that can be detected from the project files.

2. Check official React Native SDK documentation

Use the official React Native Reteno documentation as the source of truth.

Use:

Reteno React Native SDK Guide;
React Native Android SDK Setup;
React Native iOS SDK Setup;
React Native Push Notification Guide;
React Native In-App Messages Guide, when In-App validation is part of the current integration task;
React Native SDK Release Notes.

Do not start from native Android or native iOS setup unless the React Native documentation or the project setup requires native platform changes.

3. Check whether Reteno React Native SDK is already installed

If Reteno React Native SDK is already installed, do not reinstall it from scratch.

Instead:

detect the current SDK version from package.json, lock files, or installed package metadata;
check how the SDK is initialized;
check whether Android setup is complete;
check whether iOS setup is complete;
check whether push notification handling is configured;
check whether the current integration is incomplete, outdated, or misconfigured.

If Reteno React Native SDK is not installed, continue with a new React Native SDK integration flow.

4. Check SDK version and release notes

Before installing, updating, or troubleshooting the Reteno React Native SDK:

detect the current SDK version from project files, if installed;
check the official React Native SDK Release Notes;
check whether the issue may be related to an outdated SDK version, compatibility issue, migration requirement, or known fixed issue.

Do not update the SDK automatically unless the developer explicitly asks for an update or the official documentation indicates that an update is required.

If documentation and package registry versions differ, ask the developer or platform owner which version to use.

4.1 Documentation and version consistency gate

Before installing or updating the React Native SDK, compare:

selected reteno-react-native-sdk version;
React Native SDK Release Notes;
React Native compatibility;
resolved native Android SDK version;
resolved native iOS SDK version;
platform requirements;
matching official Android setup documentation;
matching official iOS setup documentation;
matching official Push Notification Guide.

If package metadata, release notes, and documentation disagree:

do not choose or upgrade a version automatically;
document the mismatch;
ask the developer or platform owner which version to use.

5. Check prerequisites

Before applying SDK changes, confirm that the required prerequisites are available.

Check or ask for:

Reteno SDK access key or approved project configuration method;
selected Reteno app/environment;
target validation platform:
- Android only;
- iOS only;
- both Android and iOS;
Android package name / applicationId, if Android validation is included;
iOS bundle ID, if iOS validation is included;
Firebase / FCM configuration;
google-services.json, if Android validation is included;
GoogleService-Info.plist, if iOS uses FCM;
APNs or FCM configuration for iOS, if iOS validation is included;
Reteno MCP access;
selected test environment for push validation;
local device or simulator automation availability, if the agent is expected to interact with the device directly.

If a prerequisite cannot be verified automatically, ask the developer for confirmation.

6. Apply React Native SDK integration changes

Use the official React Native SDK documentation to apply the integration.

Depending on the project, you may need to:

add reteno-react-native-sdk dependency;
update package.json;
run the package manager install command;
follow the exact initialization and push notification sequence from the official React Native Push Notification Guide matching the installed SDK version;
initialize the SDK only once from a stable application bootstrap location;
register all required listeners before queued event delivery starts;
preserve the application's existing permission-prompt UX;
handle and report initialization failures;
do not duplicate version-specific initialization code in this runbook;
configure SDK access key through the approved project configuration method;
register for remote notifications;
preserve existing React Native startup logic;
preserve existing Firebase setup;
preserve existing push notification handling;
preserve existing deeplink handling;
preserve existing authentication and analytics logic.

Do not overwrite existing application logic.

7. SDK access key configuration in React Native

Use the approved project configuration method for the Reteno SDK access key.

Do not hardcode the access key in committed JavaScript, TypeScript, native Android, or native iOS files.

If the project uses a local JavaScript / TypeScript config file for local evaluation:

place it in an ignored local configuration path;
provide an example file without real secrets;
import it in a way that Metro can resolve reliably;
do not print the file contents during debugging;
document the expected local filename in the final report.

If Metro cannot reliably resolve a try/catch-wrapped optional require(...), switch to a static import only when the file is intentionally local, gitignored, and documented.

If the config filename changes during the integration, report the rename and the required local action for the developer.

8. Apply Android-specific setup, if Android validation is included

Apply Android native changes only when the React Native setup requires them.

Check or update:

android/build.gradle;
android/app/build.gradle;
android/app/build.gradle.kts;
android/settings.gradle;
android/app/src/main/AndroidManifest.xml;
google-services.json;
Firebase / FCM configuration;
Android notification permission;
existing Firebase Messaging service;
existing notification handlers;
package name / applicationId;
minSdk;
Java compatibility settings;
AndroidX / Jetifier settings, according to the official guide;
notification icon / color metadata.

Starting from reteno-react-native-sdk v2.0.0, Android SDK initialization is done from JavaScript via initialize(...).

Do not add custom MainApplication initialization for basic setup unless the official documentation or the existing project setup requires it.
Before changing Android platform requirements:

detect and report the current minSdkVersion;
compare it with the requirements of the selected SDK version;
do not raise minSdkVersion without explicit developer approval;
document the compatibility impact if a change is required.

Treat a minSdkVersion increase as a product compatibility decision, not as an automatic fix.

If the app already uses a custom Firebase Messaging service, preserve it and add Reteno-compatible handling according to the official React Native Android setup guide.

9. Apply iOS-specific setup, if iOS validation is included

Apply iOS native changes only when the React Native setup requires them.

Check or update:

ios/Podfile;
ios/*.xcworkspace;
ios/*.xcodeproj;
AppDelegate;
Notification Service Extension;
App Groups;
APNs or FCM token handling;
GoogleService-Info.plist, if iOS uses FCM;
push notification permission flow;
existing UNUserNotificationCenterDelegate;
existing Firebase MessagingDelegate, if FCM is used;
existing deep link handling.

Do not overwrite existing native iOS app lifecycle or notification handling.

If the project already has custom push notification handling, preserve it and add Reteno processing calls only where required.

10. Build and run the application

After applying code changes, build or run the application when possible.

Use the platform selected for validation:

Android emulator;
physical Android device;
iOS simulator, if supported and confirmed by the developer;
physical iOS device;
another supported test environment.

If build or run fails, try to fix the issue only when it can be resolved safely through JavaScript/TypeScript code, dependency setup, native project configuration, or supported tooling.

Do not retry indefinitely.

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, dashboard changes, GUI interaction, local automation, or manual device actions are required.

Ask the developer to run the app through the appropriate tool and provide logs when the issue requires local environment access or cannot be resolved safely by the agent.

Ask for:

exact build or runtime error;
crash reason, if available;
relevant logs;
simulator, emulator, or device details;
reproduction steps.

Continue only after the developer provides the missing information or confirms the blocker.

11. Continue with MCP capability discovery and validation

After the app builds and runs, continue with MCP Capability Discovery and Validation.

Before using Reteno MCP for validation, discover which capabilities are available and authorized in the current agent environment.

If a required validation capability is unavailable, use an approved manual or Reteno UI fallback where possible and mark the step as Blocked, Manual fallback, or Pending.

Do not report the integration as complete until all required validation checks pass or a blocker is clearly documented.

12. Troubleshoot and retry failed checks

If a build, integration, or validation check fails, do not stop immediately.

For each failed check:

Identify the failed step.
Capture the observed result, error, log, MCP response, or missing status.
Check official Reteno React Native documentation, native iOS/Android documentation when relevant, SDK Release Notes, mobile push error codes, MCP results, project logs, and known SDK issue references.
Apply a safe fix if the issue can be resolved through JavaScript/TypeScript code, native project configuration, dependency setup, or available and authorized MCP capabilities.
Build, run, or validate again after applying the fix.
Continue the workflow if the issue is resolved.
If the issue requires external access, unsupported MCP capability, Reteno dashboard changes, Firebase setup, APNs/FCM setup, credentials, or admin confirmation, ask the developer or admin to complete the required step.
Document all attempted fixes and remaining blockers in the final report.

Do not repeat the same fix indefinitely. If the issue cannot be resolved after a reasonable retry, document what was tried and escalate with evidence.

13. Return the final report

At the end of the integration, return a structured final report.

Include:

detected platform and framework;
evidence used for React Native detection;
target validation platform: Android, iOS, or both;
React Native version;
Reteno React Native SDK version;
files inspected;
files changed;
dependencies added or updated;
native Android changes, if any;
native iOS changes, if any;
manual steps requested;
manual steps completed;
build/run result;
Reteno MCP connection;
local device / simulator automation status;
Reteno MCP validation results;
unresolved blockers;
recommended next steps.

Manual Setup Steps

Use manual setup only when a required step cannot be completed safely through code changes, project configuration, supported tooling, or available MCP capabilities.

Before requesting manual action, the agent must:

identify the blocked step;
explain why manual action is required;
state who should perform it: developer, admin, QA engineer, or user;
explain how validation should continue after the manual action is completed;
wait for confirmation before continuing.

Common manual actions may include:

providing the Reteno SDK access key through the approved project configuration method;
confirming the selected Reteno app/environment;
confirming Firebase / FCM / APNs setup;
confirming Reteno-side push-provider configuration;
running the app in the selected test environment;
granting notification permission;
opening the delivered test push notification;
completing login or registration for externalCustomerId validation;
confirming, creating, configuring, publishing, or attaching an In-App message in Reteno UI when MCP capabilities are unavailable.

If runtime UI interaction is required and the agent cannot perform it directly, use the manual fallback described in Appendix: Local Device and Simulator Automation.

If Reteno MCP cannot perform a required validation action, use an approved Reteno UI or manual fallback when possible and mark the step as Blocked, Manual fallback, or Pending.

After manual confirmation, continue from the next required integration or validation step.

Document all manual actions in the final report.

Validation Requirements

The agent 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.

React Native Android-only validation success criteria

For an Android-only React Native integration run, success requires:

React Native app root detected;
Android target selected and confirmed;
Reteno React Native SDK installed;
required Android native setup completed or confirmed through autolinking;
Firebase / FCM configuration confirmed;
app builds and runs on the selected Android test environment;
contact is created or found;
mobilePushToken is assigned;
token type is FCM;
test push is sent to the 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 setup is not required for an Android-only validation run unless explicitly requested.

iOS push routing

React Native iOS push validation must distinguish between two scenarios.

Direct APNs

Use this path when the selected Reteno iOS app expects an APNs token.

Verify:

bundle ID;
Team ID;
APNs sandbox or production route;
Reteno-side APNs credentials;
APNs token registration;
Reteno app configured for APNs.

Apply APNs sandbox requirements only to direct APNs validation.

FCM with APNs transport

Use this path when the selected Reteno iOS app expects an FCM token.

Verify:

Firebase project alignment;
GoogleService-Info.plist matches the iOS bundle ID;
Firebase has valid APNs credentials;
Reteno uses the corresponding Firebase project;
APNs and FCM tokens are not mixed;
the contact receives an FCM token in Reteno.

Do not apply direct APNs Reteno configuration rules to the FCM route.

Core mobile push validation

When mobile push integration is included, the following checks are required:

contact creation;
mobilePushToken assignment;
token type validation;
test push sending;
DELIVERED status;
CLICKED status;
final report.

Platform-specific token expectations

For React Native Android validation:

expected token type is FCM.

For React Native iOS validation:

expected token type is FCM if the selected Reteno iOS app is configured with FCM;
expected token type is APNs if the selected Reteno iOS app is configured with APNs.

The token assigned to the contact must match the selected Reteno mobile app configuration.

Platform-specific push validation

Validate React Native Android and React Native iOS separately.

For each selected platform, validate:

notification permission;
token registration;
token type;
foreground delivery;
background delivery;
terminated-state delivery and opening;
delivery evidence;
click or interaction evidence;
actual navigation destination.

The final report must state how each result was verified.

Evidence collected on one platform must not be treated as evidence for the other platform.

Feature-specific validation

Run feature-specific validation for every Reteno SDK feature included in the current integration task.

Feature-specific validation may include:

custom event validation;
In-App message validation;
mobile-push + In-App validation;
READ status validation;
externalCustomerId validation;
deeplink validation;
custom push data validation;
action button validation.

If a required feature-specific check cannot be completed, document the reason in the final report as one of the following:

blocker;
manual step;
unsupported MCP capability;
missing MCP capability;
unavailable test environment;
unavailable Reteno UI / admin setup.

Reteno MCP Setup Quick Check

Reteno MCP must be connected in the same environment where the AI coding agent runs.

Reteno MCP is used for Reteno-side validation:

contact lookup;
mobilePushToken verification;
token type validation;
test push creation and sending;
DELIVERED / CLICKED status checks;
feature-specific validation when the required MCP capabilities are available.

Reteno MCP is not part of the mobile app and is not configured inside the React Native project.

The Reteno MCP server endpoint is:

https://mcp.reteno.com

MCP authentication uses Reteno OAuth login. Do not use a Reteno REST API key for MCP connection.

The connected AI agent acts with the permissions of the signed-in Reteno account. Make sure the account has access to the required Reteno organization, workspace, mobile app, contacts, messages, and validation tools.

Official Reteno MCP setup guides

Use the official Reteno setup guide that matches the AI coding agent environment:

AI agent environment	Official setup guide
Claude Code / Claude Cowork	Setting Up the Reteno Plugin for Claude Code and Claude Cowork
OpenAI Codex	Setting Up the Reteno Plugin for OpenAI Codex
Cursor	Setting Up the Reteno MCP Server in Cursor
MCP server reference	Reteno MCP Server

Verify MCP connection

Before SDK validation starts, ask the agent to verify the MCP connection.

Examples:

Discover available and authorized Reteno MCP capabilities.

Are any MCP servers connected?

Expected result:

Reteno MCP server is connected;
Reteno MCP capabilities are visible;
the signed-in Reteno account has access to the selected Reteno organization, workspace, and app.

If Reteno MCP is not connected, Reteno-side validation cannot be completed.

Do not mark SDK integration as complete until Reteno MCP validation is completed or the MCP blocker is clearly documented.

If MCP cannot be connected

If Reteno MCP cannot be connected in the current AI agent environment:

continue only with integration steps that are not blocked by MCP;
do not mark the integration as complete;
report MCP validation as blocked / pending;
document which validation steps could not be completed;
use another approved MCP-enabled environment if available;
or ask the developer/admin to approve Reteno MCP access for the current environment.

Common causes:

corporate agent environment blocks external MCP connections;
third-party plugins/connectors are restricted;
network access to Reteno is blocked;
wrong Reteno account was authorized;
Reteno account does not have required permissions;
agent environment needs restart after plugin/MCP setup.

MCP Capability Discovery and Validation

After applying React Native 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 whether the connected MCP environment supports:

locating the test contact;
verifying push-token registration and token type;
selecting or creating a test mobile push message;
sending to one approved test contact;
checking delivery status;
checking click or interaction evidence;
finding In-App messages by name or ID;
getting In-App details;
checking In-App statuses.

Do not rely on predefined MCP tool names.

Do not assume support for sending pushes, retrieving DELIVERED / CLICKED statuses, or managing In-App messages.

Do not infer MCP support only from public documentation.

Require explicit developer or admin approval for any create, update, publish, send, or delete action.

Use only a non-production Reteno environment and an approved test contact.

If a capability is unavailable:

use an approved manual or Reteno UI fallback;
mark the step as Blocked, Manual fallback, or Pending;
document the limitation in the final report.

Fallback evidence when MCP status lookup is unavailable

If MCP status lookup capabilities are unavailable, return empty results, or return an error, do not assume validation failed immediately.

Use approved fallback evidence when available:

Reteno UI;
backend data;
SDK logs;
device logs;
on-device Reteno API responses;
redacted network logs;
developer / QA confirmation.

For delivery and click validation, fallback evidence may include successful Reteno API status responses from the device, such as HTTP 200 for delivery or click interaction status updates.

When fallback evidence is used:

document which MCP capability was unavailable or failed;
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 fallback evidence;
report the result as Blocked or Partial if no reliable fallback evidence is available.

In-App capabilities to discover

Before running In-App validation, discover whether the current MCP environment supports any of the following capabilities:

finding In-App messages by name or ID;
getting In-App details;
attaching an existing In-App message to a mobile push;
verifying which In-App message is attached to a push;
checking In-App statuses.

Do not assume these capabilities are available.

If a capability is unavailable, use Reteno UI, a preconfigured campaign, developer/admin confirmation, or mark the step as blocked.

Validation flow

1. Check selected Reteno mobile app configuration

Verify that the selected Reteno mobile app matches the React Native target platform.

Expected configuration:

React Native Android: FCM;
React Native iOS: FCM or APNs.

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 iOS uses APNs;
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 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, logs, or Reteno UI.

Expected result:

contactId is available;
deviceId is available, if this data can be retrieved;
platform / OS information is available;
externalCustomerId is not required at this stage;
mobilePushToken is not required at this stage.

Use contactId as the primary identifier.

If Reteno MCP supports deviceId lookup, also verify that the same contact can be found by deviceId.

3. Validate contact attributes

Check whether the anonymous contact has valid timeZone and languageCode values.

Inspect the implementation:
- find where the React Native app initializes or updates the anonymous contact;
- check whether timeZone and languageCode are passed through SDK code;
- if these values are generated automatically by the SDK, verify that the app does not override them with invalid custom values.
Verify the saved contact data in Reteno:
- use Reteno MCP, Reteno UI, backend data, or logs to open the created anonymous contact;
- confirm that the saved contact profile contains valid timeZone and languageCode values.

Expected format:

timeZone must use TZ database format, for example Europe/Kyiv, Europe/Sofia, or America/New_York;
languageCode must use RFC 5646 format, for example en, en-US, uk, uk-UA, or de-AT.

Do not use invalid values such as GMT+2, UTC+3, Kyiv, +02:00, english, EN, ua, or uk_UA.

4. Request push notification permission

Trigger or verify the push notification permission flow.

Expected result:

the app requests notification permission when required;
notification permission is granted or the current permission state is confirmed;
the SDK receives or can access the mobile push token;
the token is sent to Reteno;
the token is assigned to the anonymous contact.

If the AI agent cannot interact with the selected test environment directly, ask the developer to complete the permission step manually and continue after confirmation.

5. Verify mobile push token assignment

After push permission is granted and the SDK is initialized, use Reteno MCP to verify the contact state.

Expected result:

contactId is available;
deviceId is available, if this data can be retrieved;
mobilePushToken is available;
osName is available;
token type is available: FCM or APNs.

Expected token type:

React Native Android contact must have an FCM token;
React Native iOS contact must have an FCM token if the selected Reteno iOS app is configured with FCM;
React Native iOS contact must have an APNs token if the selected Reteno iOS app is configured with APNs.

The token assigned to the contact must match the token type configured for the selected Reteno mobile app.

6. Send a test mobile push

After the contact is created and mobilePushToken is assigned, use Reteno MCP to send a test mobile push to this contact.

Use a dedicated messageTag, for example test, to make push statuses easier to find.

Create and send the test push only to the selected test contact.

Scope the test push explicitly to the current contactId, deviceId, or mobilePushToken, depending on the available MCP capability.

Do not create or send a broad campaign during validation.

If the MCP permission classifier blocks the push action, retry only with an explicitly scoped single-contact payload.

If it is still blocked, document the MCP permission issue in the final report.

7. Verify push delivery status

After sending the test push, use Reteno MCP or backend data to check push statuses.

Expected result:

DELIVERED status is available for the test push.

If DELIVERED is not available and ERROR is present:

Check the error code.
Match the error code with Reteno mobile push error documentation.
Explain the likely reason.
Provide troubleshooting steps.

Possible causes may include:

missing or invalid mobilePushToken;
incorrect Firebase project or Sender ID;
incorrect APNs configuration;
sandbox / production mismatch;
incorrect Reteno mobile app configuration;
token type mismatch;
invalid or outdated token;
notification permission disabled;
notification channel disabled on Android;
Notification Service Extension or App Groups issue on iOS;
SDK version or compatibility issue.

8. Verify push click tracking

After DELIVERED status is available, verify that push interaction is tracked.

The test push notification must be opened in the selected test environment.

The selected test environment can be:

Android emulator;
physical Android device;
iOS simulator, if supported and confirmed by the developer;
physical iOS device;
another supported environment confirmed by the developer.

If the agent can interact with the selected test environment directly and the required local automation permissions are granted, open the push notification through the available automation tool.

For React Native Android validation:

open the notification from the Android notification shade, if needed;
tap the delivered test push notification;
if automation cannot open the notification, ask the developer or QA engineer to open it manually.

For React Native iOS validation:

if the push banner is visible, tap the banner;
if the banner exposes an Open action, tap Open;
if the banner disappears before interaction, open iOS Notification Center and tap the delivered test push notification;
if the agent cannot interact with the iOS simulator/device UI, ask the developer or QA engineer to open the notification manually.

Do not repeat screenshot-only checks indefinitely.

Do not treat inability to tap the push notification as a React Native SDK integration failure.

After the push notification is opened, use Reteno MCP to verify that the CLICKED status has been received.

Expected result:

CLICKED status is available for the same test push.

If CLICKED is missing after the push was opened, troubleshoot React Native notification click handling, native Android/iOS notification handlers, deeplink handling, and Reteno push processing calls.

9. Verify that push statuses belong to the same contact and message

For correct validation, all push statuses must belong to the same test push and the same contact.

Verify that available delivery and interaction evidence belongs to the same test contact and test message where this can be confirmed.

Use only available and verified identifiers.

Do not require full contactId, deviceId, push token, imid, iid, messageTag, requestId, or any implementation-specific field.

If identifiers are needed for troubleshooting, use redacted values only.

For core mobile push validation, verify:

DELIVERED;
CLICKED.

If READ status validation is part of the current integration task, verify READ as well.

If ERROR is present, treat it as a troubleshooting path.

SENT may be available on the backend, but it is not the main success status for delivery validation.

10. Feature-specific validation: Verify custom event delivery

Use this check when the current integration task includes custom events or explicitly asks to validate custom events.

When custom event validation is included in the integration task, this check is required and must not be skipped.

Before running this check, verify that Reteno MCP can retrieve events for the contact or that another verification method is available, such as Reteno UI, event log, backend logs, or API response.

If MCP cannot retrieve event list / count for the contact or verify that the event belongs to the expected contactId / deviceId, document the missing MCP capability as a requested capability.

Create and send a test custom event through the SDK.

Use the following event name:

testAiEvent

Expected result:

testAiEvent is received in Reteno;
the event is assigned to the same contactId / deviceId used for mobile push validation;
the event payload is available;
the event can be found in backend logs, event log, or contact activity where applicable.

11. Feature-specific validation: Verify externalCustomerId after login or registration

Use this check when the current integration task includes user identification, login, registration, or explicitly asks to validate externalCustomerId.

Before login or registration, the contact must remain anonymous.

Expected result before login or registration:

contactId is available;
deviceId is available;
platform / OS information is available;
externalCustomerId is not assigned yet.

After login or registration, the app / SDK must send a stable customer user ID to Reteno as externalCustomerId.

Expected result after login or registration:

externalCustomerId is assigned;
it is assigned to the same contact / device that was created anonymously before login or registration;
mobilePushToken remains assigned to the correct contact;
subsequent SDK events are sent to the contact with externalCustomerId.

Do not use unstable values as externalCustomerId, such as:

deviceId;
mobile push token;
temporary session ID;
random UUID generated on the device;
email, if the product has a stable backend user ID.

12. Feature-specific validation: Verify deeplink handling

Use this check when the current integration task includes deeplinks, custom push data, push links, In-App links, or explicitly asks to validate navigation behavior.

Validate separately on Android and iOS.

For each selected platform, test:

foreground state;
background state;
terminated state;
custom URL scheme;
universal link or Android App Link;
normal HTTPS URL;
actual destination screen.

Use the current React Native Push Notification Guide for version-specific behavior.

Warn and report that:

automatic link-opening behavior is platform-dependent;
push and In-App links may behave differently;
custom navigation can cause duplicate routing;
successful warm-start behavior does not validate cold start;
an Android result does not validate iOS;
an iOS result does not validate Android.

Expected result:

the app opens the expected destination screen;
the result is verified separately for each selected platform and app state;
duplicate routing or wrong-screen navigation is not observed;
any platform-specific limitation is documented.

Feature-specific validation: In-App message triggered by event

Use this check only when the current integration task includes In-App messages or explicitly asks to validate an In-App message triggered by an event.

Do not assume that Reteno MCP can create, publish, configure, inspect, trigger, or verify In-App messages.

Before running this validation, discover which MCP capabilities are available and authorized in the current agent environment.

Use only:

a non-production Reteno environment;
an approved test contact or test audience;
an approved existing or preconfigured In-App message;
a controlled app-open trigger or a uniquely named event trigger confirmed by the developer or admin.

Do not create, update, publish, configure, or trigger anything without explicit developer or admin approval.

Do not publish an integration-test In-App message to a production-wide audience.

Do not require an unverified system permission dialog as part of In-App validation.

In-App side effects

If the SDK automatically fetches or logs an existing In-App message during initialization, do not treat this as completed In-App validation.

Report it as an observed side effect only.

In-App validation is completed only when it is part of the current integration task and the required display, trigger, callback, status, or fallback evidence is verified.

If In-App validation was not requested, report it as:

not requested for this integration

To validate an In-App message triggered by an event:

Confirm that In-App validation is part of the current integration task.
Confirm the selected non-production Reteno environment.
Confirm the approved test contact or test audience.
Confirm whether an approved In-App message already exists.
If an existing In-App message should be used, ask the developer or admin to provide the In-App message name or ID.
If no approved In-App message exists, ask the developer or admin to create or confirm it in Reteno UI.
Confirm the trigger type:
- app open;
- uniquely named event;
- another approved trigger.
If an event trigger is used, ask the developer or admin to confirm the event name.
Do not hardcode eventTestInApp as a required event name. Use it only as an example if the developer confirms it.
Discover whether MCP can find the In-App message by name or ID.
If this capability is available, use MCP to find the In-App message.
If this capability is unavailable, ask the developer or admin to confirm the In-App message in Reteno UI.
Discover whether MCP can get In-App message details.
If this capability is available, use MCP to inspect the In-App message details.
If this capability is unavailable, ask the developer or admin to confirm the message details in Reteno UI.
Confirm that the In-App message is active and eligible for the approved test contact or audience.
Confirm frequency and targeting rules.
Open the app in the selected test environment.
Trigger the approved app-open condition or uniquely named event.
If the agent cannot trigger the event automatically, ask the developer or QA engineer to trigger it manually and confirm completion.
Verify that the In-App message appears in the app.
Verify display, close, error, custom-data callbacks, and link/navigation behavior when available.
If the In-App message contains a button or link, click it only when local automation is available or ask the developer / QA engineer to click it manually.
Verify available In-App evidence using MCP, Reteno UI, backend data, event log, or logs.
Document which validation actions were completed through MCP and which required manual or Reteno UI fallback.

Expected result:

the In-App message is approved for validation;
the In-App message exists in a non-production Reteno environment;
the In-App message is active and eligible for the approved test contact or audience;
the trigger is confirmed as app open, uniquely named event, or another approved trigger;
the trigger event is received in Reteno when event validation is part of the current task;
the In-App message appears in the app when the configured trigger and eligibility rules are satisfied;
display, close, error, custom-data callbacks, and link/navigation behavior are verified when available;
Read, Click, or Clicked In-App statuses are verified only if the required MCP, UI, backend, or log evidence is available;
unavailable capabilities are documented as Blocked, Manual fallback, or Pending;
the event, In-App message, and available statuses are correlated only through verified and available evidence.

14. Feature-specific validation: Mobile-push + In-App flow

Use this check only when the current integration task includes a mobile-push + In-App flow or explicitly asks to validate this flow.

Do not assume that Reteno MCP can create, publish, attach, inspect, send, or verify In-App messages or mobile push messages.

Before running this validation, discover which MCP capabilities are available and authorized in the current agent environment.

Use only:

a non-production Reteno environment;
an approved test contact or test audience;
an approved existing or preconfigured In-App message;
an approved mobile push message or campaign created specifically for validation.

Do not create, update, publish, attach, or send anything without explicit developer or admin approval.

Do not publish an integration-test In-App message to a production-wide audience.

Do not require an unverified system permission dialog as part of In-App validation.

To validate the mobile-push + In-App flow:

Confirm that mobile-push + In-App validation is part of the current integration task.
Confirm the selected non-production Reteno environment.
Confirm the approved test contact or test audience.
Confirm whether an approved In-App message already exists.
If an existing In-App message should be used, ask the developer or admin to provide the In-App message name or ID.
If no approved In-App message exists, ask the developer or admin to create or confirm it in Reteno UI.
Discover whether MCP can find the In-App message by name or ID.
If this capability is available, use MCP to find the In-App message.
If this capability is unavailable, ask the developer or admin to confirm the In-App message in Reteno UI.
Discover whether MCP can get In-App message details.
If this capability is available, use MCP to inspect the In-App message details.
If this capability is unavailable, ask the developer or admin to confirm the message details in Reteno UI.
Discover whether MCP can attach an existing In-App message to a mobile push.
If this capability is available and explicitly approved, attach the In-App message to the mobile push.
If this capability is unavailable, ask the developer or admin to attach or confirm the attachment manually in Reteno UI.
Discover whether MCP can verify which In-App message is attached to the mobile push.
If this capability is available, verify the attachment through MCP.
If this capability is unavailable, ask the developer or admin to confirm the attachment in Reteno UI.
Discover whether MCP can send the mobile push to one approved test contact.
If this capability is available and explicitly approved, send the mobile push only to the approved test contact.
If this capability is unavailable, ask the developer or admin to send the test push manually through Reteno UI.
Verify delivery evidence using available MCP capabilities, Reteno UI, backend data, or logs.
Open the delivered push notification in the selected test environment.
If the agent cannot open the push automatically, ask the developer or QA engineer to open it manually and confirm completion.
Verify that the app opens after the push interaction.
Verify that the In-App message appears, if this is expected for the configured flow.
If the In-App message contains a button or link, click it only when local automation is available or ask the developer / QA engineer to click it manually.
Verify available In-App evidence using MCP, Reteno UI, backend data, or logs.
Document which validation actions were completed through MCP and which required manual or Reteno UI fallback.

Expected result:

the mobile push is sent only to the approved test contact or test audience;
delivery evidence is available through MCP, Reteno UI, backend data, or logs;
the In-App message is attached to the mobile push or the attachment is confirmed manually;
the app opens after the push notification is opened;
the In-App message appears when the configured trigger and eligibility rules are satisfied;
display, close, error, custom-data callbacks, and link/navigation behavior are verified when available;
Read, Click, or Clicked In-App statuses are verified only if the required MCP, UI, backend, or log evidence is available;
unavailable capabilities are documented as Blocked, Manual fallback, or Pending;
push, In-App message, and available statuses are correlated only through verified and available evidence.

React Native 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.

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 the issue requires:

external access;
credentials;
signing changes;
Reteno dashboard changes;
Firebase console changes;
Apple Developer account changes;
GUI interaction;
manual device actions.

Record attempted fixes and the first actionable error.

Do not retry indefinitely.

Do not continue MCP validation until the app builds and runs, or the build/run blocker is clearly documented.

Recurring React Native SDK issue checks

When troubleshooting React Native SDK integration, check recurring SDK issue patterns before escalating.

Common React Native-related issues may include:

DELIVERED or CLICKED statuses are missing;
mobilePushToken is missing;
pushSubscribed=false;
Firebase / FCM token mismatch or missing token;
APNs / FCM mismatch on iOS;
incorrect Reteno mobile app configuration;
SDK version compatibility issues;
SDK initialization issues;
Metro or package manager issues;
Android Gradle build issues;
iOS Pod install or Xcode build issues;
events are not tracked;
deeplink handling does not work;
In-App messages do not appear;
native iOS or Android configuration conflicts.

Use these patterns as troubleshooting hints. Always verify the issue against the current project, official Reteno React Native documentation, native platform documentation when relevant, MCP results, logs, and build output before applying a fix.

React Native SDK dependency is missing or incorrect

If the React Native SDK dependency is missing or incorrect, check:

package.json;
package manager lock file;
package manager used by the project: npm, Yarn, pnpm, or another package manager;
installed reteno-react-native-sdk version;
official React Native SDK documentation;
release notes.

Do not switch package managers.

Use the package manager already used by the project.

SDK initialization is missing or incorrect

If the SDK does not initialize, check:

React Native app entry point;
root component initialization;
whether initialize(...) is called once;
whether SDK access key is provided through the approved configuration method;
whether event handling is initialized according to the official docs;
whether push registration is called according to the official docs;
whether initialization is delayed by app startup, auth, navigation, or remote config logic.

Expected result:

SDK initialization path is executed when the app starts;
anonymous contact can be created;
SDK key is not left as a placeholder;
initialization does not break existing app startup.

Android build fails

If Android build fails, check:

android/build.gradle;
android/app/build.gradle;
Gradle plugin version;
Kotlin version;
Java compatibility settings;
minSdk;
AndroidX / Jetifier settings;
Firebase dependencies;
google-services.json;
package name / applicationId;
duplicate Firebase Messaging service definitions.

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, or manual device actions.

If the issue requires local environment access or cannot be resolved safely, ask the developer to run the app through Android Studio or Gradle and provide the following:

exact error message;
crash reason, if available;
relevant logs;
emulator, or device details;
reproduction steps.

Firebase `databaseURL` validation error

If explicit Firebase initialization fails with:

Missing or invalid FirebaseOptions property 'databaseURL'

first verify whether the project actually uses Firebase Realtime Database.

If Realtime Database is not used but Firebase options validation requires a syntactically valid databaseURL, ask the developer or React Native Firebase SME to confirm the accepted workaround.

A conventional placeholder may be derived from the Firebase project ID only when approved by the developer.

Do not treat this placeholder as a credential.

Do not invent or add Realtime Database usage.

Document:

the original error;
whether Realtime Database is used;
whether a placeholder databaseURL was added;
who approved the workaround;
where the Firebase config lives;
whether push validation passed after the workaround.

iOS build fails

If iOS build fails, check:

ios/Podfile;
CocoaPods installation;
pod install;
.xcworkspace;
AppDelegate;
Notification Service Extension;
App Groups;
signing and capabilities;
GoogleService-Info.plist, if iOS uses FCM;
APNs / FCM setup.

If the issue requires local environment access or cannot be resolved safely, ask the developer to run the app through Xcode and provide the following:

exact error message;
Xcode logs;
simulator or device details;
reproduction steps.

iOS APNs entitlement key check

When configuring iOS push entitlements, verify the exact entitlement key included in the provisioning profile and final code signature.

The APNs environment entitlement key must be:

aps-environment

Do not replace it with:

com.apple.developer.aps-environment

Xcode entitlement merging depends on exact key names.

Expected result:

the provisioning profile grants aps-environment;
the app entitlements file uses aps-environment;
the final signed app contains aps-environment;
push token registration works in the selected development or production environment.

If push token registration or delivery fails, inspect the final signed entitlements before assuming the SDK integration is broken.

Metro or package manager fails

If Metro bundler or package installation fails, check:

package manager command;
lock file;
Node version;
React Native version;
installed package versions;
Metro cache;
duplicate packages;
autolinking status.

Do not delete lock files or change package manager without developer confirmation.

Contact is not found

If Reteno MCP cannot find the contact, check:

SDK initialization;
SDK access key;
app launch;
network connection;
whether the app was run after SDK integration changes;
whether Reteno MCP has access to the correct Reteno app or environment;
selected target platform: Android, iOS, or both.

Expected result:

the contact is found by contactId;
the contact has the expected React Native platform / OS information.
If the contact still cannot be found, document this as a blocker.

`mobilePushToken` is missing

If the contact exists but mobilePushToken is missing, check:

whether push notification permission was requested;
whether permission is granted;
whether the app received an FCM or APNs token;
whether the token was passed to Reteno;
whether token type matches the selected Reteno app configuration;
whether Android uses FCM;
whether iOS uses FCM or APNs;
whether existing notification handlers block token propagation;
SDK version.

Expected result:

mobilePushToken is assigned to the contact;
token type matches the selected Reteno app configuration.

`pushSubscribed=false`

If pushSubscribed=false or the contact cannot receive pushes, check:

notification permission;
notification channel state on Android;
OS-level notification settings;
whether the app received a push token;
whether the token was passed to Reteno;
whether the selected Reteno app uses the correct push provider configuration;
whether the user should be resubscribed after notifications are re-enabled.

Expected result:

notification permission is granted;
mobilePushToken is available;
contact can receive push notifications.

Token type or push provider mismatch

If the token type does not match Reteno configuration, check:

selected Reteno mobile app;
Android package name / applicationId;
iOS bundle ID;
Firebase project;
google-services.json;
GoogleService-Info.plist;
APNs configuration;
FCM Sender ID;
whether the contact has the expected token type.

Expected result:

React Native Android contact has an FCM token;
React Native iOS contact has an FCM token if the selected Reteno iOS app is configured with FCM;
React Native iOS contact has an APNs token if the selected Reteno iOS app is configured with APNs.

Duplicate Firebase registries in app target and framework target

Some React Native applications link native modules through a separate framework or SDK target.

Before troubleshooting missing FCM tokens on iOS, inspect whether Firebase is linked into more than one binary target, such as:

main app target;
React Native SDK/framework target;
embedded app framework;
custom native framework.

Duplicate static Firebase copies can cause runtime warnings like:

Class ... is implemented in both ...

and can make Firebase Messaging inside one target unable to see the default Firebase app configured in another target.

If duplicate Firebase registries are suspected:

inspect Podfile targets;
inspect linked Firebase pods per target;
inspect runtime warnings;
verify which target owns Firebase Messaging;
verify where FirebaseApp.configure() or initializeApp() runs;
ask an iOS / React Native SME to confirm the single-owner Firebase setup.

Do not remove Firebase Analytics, Crashlytics, Messaging, or app-level Firebase pods automatically.

If Firebase ownership is changed for validation, document:

which target previously linked Firebase;
which target owns Firebase after the change;
whether Analytics / Crashlytics collection changed;
whether the change is test-only;
whether production review is required.

`DELIVERED` status is missing

If the test push is sent but DELIVERED status is missing, check:

mobilePushToken;
token type: FCM or APNs;
Reteno mobile app configuration;
FCM configuration;
APNs configuration;
Notification Service Extension and App Groups for iOS;
notification permission;
notification channel state on Android;
selected test environment;
SDK version;
push error codes.

If ERROR is present, follow these steps:

Check the error code.
Match the error code with Reteno mobile push error documentation.
Explain the likely reason.
Provide the next troubleshooting step.

`CLICKED` status is missing

If DELIVERED status is available but CLICKED status is missing, check:

whether the developer opened the test push notification;
whether the app opened after the push notification was tapped;
push click listener / handler setup;
Reteno push processing calls;
deeplink or launcher activity behavior;
existing notification handlers;
whether the push belongs to the same contact and message.

After the developer confirms that the push notification was opened, use Reteno MCP to check CLICKED again.

Expected result:

CLICKED status is available for the same test push.

Deeplink handling does not work

If deeplink handling does not work after push click, check:

React Native linking configuration;
native Android intent filters;
native iOS URL schemes / associated domains;
React Navigation deep link setup, if used;
onCreate / onNewIntent on Android, if relevant;
AppDelegate / SceneDelegate on iOS, if relevant;
custom data payload;
whether the push contains a link the app can handle;
existing deeplink handling logic that must be preserved.

Do not overwrite existing deeplink handling.

Add Reteno-related processing only where required.

Events are not tracked

If events are not tracked, check:

SDK initialization;
contact assignment;
network connection;
SDK version;
event name;
event payload;
whether the event is sent before SDK initialization is complete;
whether Reteno MCP, Reteno UI, logs, or event log can verify the event;
whether the issue is specific to Android or iOS.

If MCP cannot retrieve event list / count for the contact, document this as a missing MCP capability.

In-App messages do not appear

Run this troubleshooting when In-App validation is part of the current integration task.

Check:

SDK version;
whether In-App is included in the current integration task;
whether the In-App message exists and is active;
whether the contact belongs to the required segment;
whether the trigger event was received;
whether the In-App display rules match the test scenario;
whether the issue is Android-specific or iOS-specific;
whether MCP can find or verify the In-App message;
whether missing MCP capabilities prevent validation.

If the required MCP capability is unavailable, use Reteno UI, a preconfigured campaign, developer/admin confirmation, backend data, or mark the step as Blocked, Manual fallback, or Pending.

MCP capability is unavailable

If Reteno MCP cannot perform a required validation action:

document which capability is unavailable;
continue with the remaining validation steps where possible;
use an approved manual or Reteno UI fallback when possible;
include the missing capability in the final report;
report the limitation as Blocked, Manual fallback, or Pending.

Do not mark the integration as complete if a required validation step could not be verified.

Metro server belongs to another project

If React Native runtime or bundling behaves unexpectedly, verify that the Metro server belongs to the current project.

Check whether port 8081 is already used by another Metro process.

If another project's Metro server is running:

stop the unrelated Metro server;
start Metro from the current application root;
rebuild or reload the app;
document this as an unrelated local environment issue, not as a Reteno SDK integration failure.

Do not continue debugging SDK initialization until the app is connected to the correct Metro server.

Build or run fails

If the app does not build or run, check:

dependency setup;
SDK version;
package manager configuration;
Metro bundler;
native Android project configuration;
native iOS project configuration;
Firebase plugin configuration;
package name / applicationId;
iOS bundle ID;
google-services.json;
GoogleService-Info.plist;
selected test environment configuration;
runtime crash logs, if available.

Try to resolve the issue only when it can be fixed safely through JavaScript/TypeScript code, dependency setup, native project configuration, or supported tooling.

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, or manual device actions.

When escalation is required, ask the developer to run the app through React Native CLI, Android Studio, Gradle, Xcode, CocoaPods, or the relevant project tool and provide:

exact error message;
crash reason, if available;
relevant logs;
simulator, emulator, or device details;
reproduction steps.

Do not continue MCP validation until the app builds and runs, or the build/run blocker is clearly documented.

Final Report Format

At the end of the integration, return a structured final report.

Do not report only that the integration is complete.

Include what you inspected, what you changed, what you validated, what could not be validated, and what still requires attention.

Platform scope reporting

If the current React Native integration run is Android-only, report iOS as not requested for this integration.

Do not treat iOS setup gaps as blockers for an Android-only run.

If iOS is requested later, report the required follow-up items separately, such as:

push entitlement;
GoogleService-Info.plist, if iOS uses FCM;
APNs / FCM route decision;
Notification Service Extension;
App Groups;
iOS build/run validation.

If the current React Native integration run is iOS-only, report Android as not requested for this integration.

Do not treat missing Android setup as a blocker for an iOS-only run.

Required report fields

Use the table below as the final report template.

Fill in the Result column after completing the integration and validation flow.

If a field cannot be verified, explain why and mark it as one of the following:

not available;
not applicable;
blocked;
pending manual action;
not requested for this integration.

Do not leave required validation fields empty.

Area	Result
Report type	Complete / Partial
Overall status	Passed / Passed with warnings / Blocked / Failed
Repository / project
Commit / revision
Initial branch
Current branch
Initial worktree state	Clean / Dirty / Unknown
Application root
Application type	Bare React Native / Bare RN with Expo modules / Expo prebuild / Expo managed / Other
Target validation platform	Android / iOS / Both
React Native version
React Native architecture mode	Old / New / Unknown
Package manager	npm / Yarn / pnpm / other
Package manager detection evidence
Reteno React Native SDK version
Resolved native Android SDK version, if applicable
Resolved native iOS SDK version, if applicable
Documentation/version consistency	Passed / Warning / Blocked
SDK access key status	Provided / Placeholder / Missing
Firebase / FCM configuration	Confirmed / Needs confirmation / Not applicable
iOS push route, if applicable	Direct APNs / FCM with APNs transport / Not applicable
Existing notification/deeplink handlers	Preserved / Extended / Replaced with approval / Needs review
Local config file used
Local config file printed in output	Yes / No
Secret exposure detected	Yes / No
Secret rotation recommended	Yes / No / Not applicable
Metro server status	Correct project / Wrong project / Not checked / Not applicable
Metro port conflict	Yes / No / Not checked
Local automation method	mobile-mcp / adb / uiautomator / Android Studio / Manual / Not used
MCP status lookup result	Completed / Empty / Error / Not available / Not run
Fallback validation evidence	MCP / Reteno UI / SDK logs / device logs / on-device API response / backend data / manual confirmation / none
Platform not covered	iOS / Android / None
Platform not covered reason
Files changed
Dependencies added or updated
Build result	Passed / Failed / Not run
Run result	Passed / Failed / Not run
Test environment	Android emulator / Android device / iOS simulator / iOS device / Other
Runtime interaction method	Automation / Manual / Not run
Reteno MCP connection	Connected / Unavailable / Blocked
MCP capabilities discovered
MCP validation actions completed
Missing MCP capabilities
Contact lookup result	Found / Not found / Not run
Push token result	Present / Missing / Not run
Token type	FCM / APNs / Unknown / Not run
Test push result	Sent / Not sent / Blocked / Not run
Delivery result	DELIVERED / ERROR / Missing / Not run
Click result	CLICKED / Missing / Not run
Android validation result, if applicable	Passed / Failed / Blocked / Not run
iOS validation result, if applicable	Passed / Failed / Blocked / Not run
Selected iOS push route	Direct APNs / Firebase-FCM / Not applicable
Initial iOS push route attempted	Direct APNs / Firebase-FCM / Not applicable
iOS push route changed	Yes / No
Reason for iOS route change
Reteno mobile app token type	FCM / APNs / Unknown
Token type verified	FCM / APNs / Not verified
React Native Firebase packages added	`@react-native-firebase/app` / `@react-native-firebase/messaging` / none
React Native Firebase SPM disabled	Yes / No / Not applicable
`use_frameworks!` changed	Yes / No
Modular headers scope	None / Global / Scoped
Duplicate Firebase registry detected	Yes / No / Unknown
Firebase owner after changes	App target / Framework target / Other / Not changed
Explicit Firebase `initializeApp(...)` required	Yes / No / Not applicable
Firebase `databaseURL` workaround used	Yes / No / Not applicable
iOS embedded extensions checked	Yes / No / Not applicable
Extension bundle ID prefix valid	Yes / No / Not applicable
Extension excluded from test build	Yes / No
Exclusion reason
Sandbox bundle ID used	Yes / No
Merge readiness	Ready / Not ready / Not applicable
Production follow-up required	Yes / No
Deeplink validation, if requested	Passed / Failed / Blocked / Not requested
In-App validation, if requested	Passed / Failed / Blocked / Not requested
Custom event validation, if requested	Passed / Failed / Blocked / Not requested
externalCustomerId validation, if requested	Passed / Failed / Blocked / Not requested
Manual fallbacks used
Blockers
Warnings
Rollback instructions
Recommended next steps

If iOS bundle ID, Firebase ownership, embedded extensions, CocoaPods linkage, or React Native Firebase setup was changed for sandbox validation, report:

Overall status: Passed with warnings
Merge readiness: Not ready / needs native React Native review
Production follow-up required: Yes

Do not report a sandbox-native workaround as production-ready.

Do not hide test-only changes such as extension exclusion, Firebase ownership changes, or linkage changes inside the general integration summary.

Do not require full contactId, deviceId, push token, imid, iid, messageTag, requestId, or any implementation-specific MCP response field.

If identifiers are needed for troubleshooting, include redacted values only.

Platform-specific fields are conditional. Do not fill Android-only fields for iOS-only validation, and do not fill iOS-only fields for Android-only validation.

Report rules

The report type must be Partial if any required build, run, runtime interaction, Reteno MCP validation, or feature-specific validation step was skipped, blocked, or not verified.

Use Passed only when all required validation checks for the current integration task pass.

Use Passed with warnings only when the required validation passes but there are non-blocking warnings, such as manual fallback, version mismatch warning, simulator limitation, or non-critical feature not requested.

Use Blocked when the integration cannot continue because of missing credentials, missing Reteno MCP, unavailable test environment, unavailable Firebase/APNs setup, 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 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 Secret exposure detected: Yes and Secret rotation recommended: Yes.

Do not include the exposed value itself.

Appendix: Local Device and Simulator Automation

Reteno MCP and local device/simulator automation are separate.

Reteno MCP is used for Reteno-side validation:

contact lookup;
mobilePushToken verification;
token type validation;
test push creation and sending;
DELIVERED / CLICKED status checks;
feature-specific validation when the required MCP capabilities are available.

Local device or simulator automation is used for React Native runtime interaction:

launching the React Native app;
interacting with Android emulator, physical Android device, iOS simulator, or physical iOS device;
granting notification permission;
opening the delivered test push notification;
tapping an In-App message button, if In-App validation is part of the current integration task;
completing login or registration steps, if externalCustomerId validation is part of the current integration task.

For React Native Android validation, local automation may include mobile-mcp.

For React Native iOS validation, local automation may include iOS simulator/device automation or manual interaction by the developer or QA engineer.

Physical iOS device diagnostics may be limited outside Xcode

When validating on a physical iOS device without an attached Xcode debugging session, do not assume that all logs are visible.

Possible limitations:

devicectl --console may not show app logs;
console.log / console.error may not appear;
native os_log output may be filtered;
Metro debugging may be unavailable;
iproxy / libimobiledevice may not provide the required reverse debugging path.

If logs are unavailable, use approved temporary diagnostics only when necessary, such as:

visible UI confirmation;
temporary debug screen;
temporary Alert.alert(...);
device screenshots;
Reteno UI;
SDK logs visible through another channel;
MCP / backend evidence.

Remove temporary diagnostic instrumentation before the final code handoff unless the developer explicitly asks to keep it.

Document:

which diagnostics were attempted;
which diagnostics failed;
what fallback evidence was used;
which temporary diagnostics were removed.

Claude Code and mobile-mcp

For Claude Code, if mobile-mcp was added during the current or previous session, restart Claude Code before continuing. The tool may not be available until the agent environment is restarted.

Example setup command:

claude mcp add mobile-mcp -- npx -y @mobilenext/mobile-mcp@latest

After restart, ask the agent to verify that local automation tools are loaded.

Manual fallback

If local device or simulator automation is unavailable, do not treat this as a React Native SDK integration failure.

Ask the developer or QA engineer to perform the required runtime actions manually:

run the app;
grant notification permission;
open the delivered test push notification;
tap an In-App message button, if required;
complete login or registration, if required.

After the manual action is confirmed, continue Reteno MCP validation from the next required step.

Do not mark the integration as complete until runtime validation and Reteno MCP validation are completed, or the blocker is clearly documented.

React Native Android local automation fallback

For React Native Android validation, local automation may include:

mobile-mcp;
adb;
uiautomator;
Android Studio tools;
manual developer / QA interaction.

If mobile-mcp is unavailable but another approved local automation method works, such as adb or uiautomator, use it and document the method in the final report.

This is not a React Native SDK integration failure.

The agent must document:

which local automation method was used;
which runtime actions were completed;
whether notification permission was granted;
whether the delivered push notification was opened;
whether Reteno MCP validation continued after the runtime action.

Purpose

Agent Role

Quick Start Prompt

Source of Truth

Agent Behaviour Rules

Change-safety boundaries

Native lifecycle preservation

iOS push route preflight: APNs vs FCM

Native dependency safeguards

React Native Firebase dependency mode: SPM vs CocoaPods

Scoped modular headers for Firebase Swift pods

Explicit Firebase initialization from JavaScript

Android minSdkVersion safeguard

SDK demo app exclusion

Sandbox Firebase / app identity validation path

Test-only native changes and merge readiness

iOS embedded extension bundle ID check

Retry and escalation policy

React Native Project Detection

Expo detection guard

Package manager detection

Required Inputs

Security rules

Secret handling during debugging

Developer Preparation Checklist

1. Project access

2. Reteno setup

3. Firebase / APNs setup

3.1 Server-side Firebase / APNs preflight

4. Test environment

iOS simulator and sandbox policy

5. MCP and local automation tools

6. Build and runtime logs

7. Feature-specific validation preparation

8. Pre-flight result

React Native SDK Integration Workflow

0. Prepare a safe working branch

1. Inspect the project

2. Check official React Native SDK documentation

3. Check whether Reteno React Native SDK is already installed

4. Check SDK version and release notes

4.1 Documentation and version consistency gate

5. Check prerequisites

6. Apply React Native SDK integration changes

7. SDK access key configuration in React Native

8. Apply Android-specific setup, if Android validation is included

9. Apply iOS-specific setup, if iOS validation is included

10. Build and run the application

11. Continue with MCP capability discovery and validation

12. Troubleshoot and retry failed checks

13. Return the final report

Manual Setup Steps

Validation Requirements

React Native Android-only validation success criteria

iOS push routing

Direct APNs

FCM with APNs transport

Core mobile push validation

Platform-specific token expectations

Platform-specific push validation

Feature-specific validation

Reteno MCP Setup Quick Check

Official Reteno MCP setup guides

Verify MCP connection

If MCP cannot be connected

MCP Capability Discovery and Validation

MCP capability discovery

Fallback evidence when MCP status lookup is unavailable

In-App capabilities to discover

Validation flow

1. Check selected Reteno mobile app configuration

2. Create or initialize an anonymous contact

3. Validate contact attributes

4. Request push notification permission

5. Verify mobile push token assignment

6. Send a test mobile push

7. Verify push delivery status

8. Verify push click tracking

9. Verify that push statuses belong to the same contact and message

10. Feature-specific validation: Verify custom event delivery

Android `minSdkVersion` safeguard

Firebase `databaseURL` validation error

`mobilePushToken` is missing

`pushSubscribed=false`

`DELIVERED` status is missing

`CLICKED` status is missing