iOS AI-Assisted Integration

Purpose

This runbook helps an AI coding agent integrate the Reteno iOS SDK into a native iOS 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 iOS SDK into an existing native iOS application.

Your goal is not only to update the code, but also to validate that the SDK integration works correctly through build/run and Reteno MCP validation.

Quick Start Prompt

Use this iOS runbook as your operating instruction.

Integrate the Reteno iOS SDK from scratch into the selected native iOS application.

First inspect the project and detect the iOS project structure, dependency manager, app lifecycle, app target, bundle ID, existing Reteno usage, existing push notification setup, FCM/APNs setup, Notification Service Extension, App Groups, and existing notification handling logic.

Use the official Reteno iOS SDK Setup Guide as the primary source of truth for iOS-specific SDK installation, configuration, initialization, push setup, Notification Service Extension, App Groups, and token handling.

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

Use the official Mobile Push Error Codes when push validation fails and an ERROR status or push error code is available.

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.

Before MCP-based validation, complete the Reteno MCP Setup Quick Check. If Reteno MCP is not connected, document MCP validation as blocked and do not mark the integration as complete.

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

Preserve existing application logic. Do not overwrite push notification handlers, Firebase configuration, APNs configuration, deeplink handling, authentication flow, analytics logic, local notification handling, or app lifecycle code.

Use the existing iOS project setup. Do not switch dependency managers, app lifecycle patterns, push providers, token handling mode, 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;
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, stop before modifying files and ask the developer to confirm how to proceed.

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 iOS test environment confirmed by the developer. This can be an iOS simulator, physical iOS device, or another supported iOS test environment.

Do not assume that a physical iOS device is required if the developer confirms that push validation works in the selected iOS simulator.

After applying SDK changes, attempt to build and run the application in the selected iOS test environment.

If build/run fails after two attempts to fix the same issue, ask the developer to run the app through Xcode or xcodebuild and provide the exact error, crash reason, relevant logs, simulator/device details, and reproduction steps.

Do not stop after code changes.

After the app builds and runs, validate the integration through Reteno MCP:

find the contact;
verify contactId and deviceId, if available;
verify mobilePushToken;
identify token type: FCM or APNs;
confirm that token type matches the selected Reteno iOS app configuration;
send a single-contact test push;
verify DELIVERED;
open the push notification in the selected iOS test environment;
verify CLICKED after the push notification is opened.

Validate every Reteno SDK feature that you integrate, modify, or are explicitly asked to verify.

At minimum, for iOS 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, READ status, or externalCustomerId.

If a step cannot be completed programmatically, ask for the required manual action and continue after confirmation.

If Reteno MCP is unavailable, document Reteno-side validation as blocked and continue only with integration steps that are not blocked by MCP.

If local simulator/device automation is unavailable, ask the developer to perform runtime interactions manually, such as granting push permission or opening the test push notification.

When verifying CLICKED on iOS, do not rely only on a screenshot or a single banner tap.

After DELIVERED is confirmed, the test push notification must be opened in the selected iOS test environment.

Use this iOS push-opening strategy:

If the push banner is visible, tap the banner.
If tapping the banner shifts it and exposes an Open action, tap Open.
If the banner disappears before interaction, open Notification Center and tap the delivered test push notification there.
If the push is visible on the lock screen and tapping exposes Open, tap Open.
If the agent cannot tap the banner, tap Open, open Notification Center, or interact with the simulator/device UI, ask the developer or QA engineer to open the test push manually.

Do not repeat screenshot-only checks indefinitely.

After the push notification is opened manually or automatically, continue Reteno MCP validation and verify CLICKED.

If an MCP action 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 SDK integration.
Note: Before making changes, verify which sources you can access.

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 iOS project structure, dependency manager, app lifecycle, bundle ID, existing Reteno usage, existing push setup, FCM/APNs setup, Notification Service Extension, App Groups, notification handlers, and files to modify	Ask the user to open the project in the AI coding agent or provide the required project files
Reteno MCP	Check whether Reteno MCP is connected in the AI agent environment and list the available Reteno MCP tools/actions	Read contacts, verify mobile push token assignment, send test push notifications, check push statuses, and verify events	Ask the user to connect Reteno MCP. If MCP validation is required and unavailable, report this as a blocker
Reteno iOS SDK Setup Guide	Open Reteno iOS SDK Setup Guide	Use it as the primary source of truth for iOS-specific SDK installation, configuration, initialization, push setup, Notification Service Extension, App Groups, and token handling	Ask the user to provide the relevant iOS SDK documentation page
Reteno `llms.txt`	Open `https://docs.reteno.com/llms.txt`	Use it as the AI-readable documentation index. It helps you find the latest Reteno documentation pages, Markdown docs, SDK guides, and API references	Use direct documentation links or ask the user to provide the relevant Reteno documentation page
SDK Release Notes	Open `https://docs.reteno.com/reference/sdk-release-notes`	Check SDK versions, release history, compatibility notes, migration-related changes, and known fixes	Ask the user or developer to confirm the SDK version and required setup
Mobile push error codes	Open `https://docs.reteno.com/docs/error-codes-for-mob-push-notifications`	Troubleshoot failed test push validation, especially when push status `ERROR` is present	Ask the user or Support team to provide the relevant error code explanation
Known SDK issues/troubleshooting reference	Use the provided recurring SDK issues summary, if available in the current task or workspace	Troubleshoot common SDK integration issues, missing statuses, token configuration issues, SDK version issues, and platform-specific gaps	if unavailable, use official Reteno documentation, SDK Release Notes, mobile push error codes, MCP results, and project logs

Note — Reteno MCP: Reteno MCP must be connected in the same environment where the AI coding agent runs. Use Reteno MCP for actions such as reading contacts, checking mobile push tokens, sending test pushes, and verifying statuses.

Note — Reteno llms.txt: Reteno llms.txt is a documentation index for AI agents. Use it to find the latest Reteno documentation pages, SDK guides, and API references. It does not replace Reteno MCP validation.

Agent Behaviour Rules

Follow these rules throughout the iOS SDK integration:

Inspect the project before making any code changes.
Detect the iOS project structure, dependency manager, app lifecycle, bundle ID, current SDK version, FCM/APNs setup, push notification setup, Notification Service Extension, App Groups, and existing 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 iOS project setup. Do not switch dependency managers, app lifecycle patterns, push providers, token handling mode, or SDK versions unless the developer explicitly confirms this.
Preserve existing application logic.
Do not overwrite existing push notification handlers, Firebase configuration, APNs configuration, deeplink handling, authentication flow, analytics logic, local notification handling, or app lifecycle code.
Do not hardcode secrets, credentials, SDK access keys, Firebase keys, APNs credentials, private keys, certificates, service account data, 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.
For evaluation, test, or temporary integration runs, create and use a temporary local branch unless the developer explicitly confirms another branch.
Do not make temporary integration changes directly on main or master.
If a step cannot be completed programmatically, ask the developer, admin, user, or QA engineer to complete it manually.
After applying code changes, continue validation.
Use Reteno MCP for validation actions when MCP tools are available.
Validate every Reteno SDK feature that is integrated, modified, or explicitly requested.
Do not report the integration as complete until all required validation checks pass or a blocker is clearly documented.
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 code, Xcode project configuration, dependency setup, entitlements, capabilities, or supported MCP actions.
Do not change external app configuration, credentials, APNs/FCM setup, sandbox/production settings, Firebase project settings, Apple Developer account settings, or Reteno dashboard settings without explicit developer or admin confirmation.

iOS Project Detection

Use this runbook only for native iOS applications.

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

.xcodeproj;
.xcworkspace;
Podfile;
Package.swift;
AppDelegate;
SceneDelegate;
SwiftUI app entry point;
Info.plist;
entitlements file;
iOS target configuration;
Notification Service Extension;
App Groups;
APNs / FCM push configuration.

Before making changes, detect:

iOS project structure;
dependency manager: Swift Package Manager or CocoaPods;
app lifecycle: UIKit / AppDelegate, SceneDelegate, SwiftUI, or mixed setup;
app target;
bundle ID;
deployment target;
current Reteno SDK usage, if any;
current Reteno SDK version, if installed;
existing push notification setup;
existing local notification setup;
existing UNUserNotificationCenterDelegate;
existing Firebase MessagingDelegate, if FCM is used;
FCM or APNs token handling;
Notification Service Extension;
App Groups;
deeplink handling;
authentication or user identification flow.

Do not use this native iOS runbook directly for Android, Flutter, React Native, Expo, Ionic, Cordova, or Unity projects.

If the project is cross-platform, use the corresponding cross-platform runbook first and apply native iOS steps only when that runbook or project setup requires native iOS changes.

Required Inputs

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

Before asking the developer, inspect the project and detect:

iOS project structure;
dependency manager;
current Reteno SDK version, if installed;
app lifecycle or entry point;
existing Reteno SDK usage;
existing push notification setup;
existing Firebase, APNs, or notification handlers;
iOS bundle ID;
existing Notification Service Extension;
existing App Groups;
existing user identification or login flow, if present.

Required for iOS SDK integration

Ask for these values only if they are missing, unclear, or cannot be detected automatically:

Reteno SDK access key or approved project configuration method for providing it;
Reteno app or environment name;
environment type: development, staging, or production;
iOS bundle ID, if it cannot be detected from the project;
confirmation which Reteno mobile app should be used for the current validation run;
confirmation whether the selected Reteno iOS app is configured for FCM or APNs;
confirmation whether the selected Reteno iOS app is configured for sandbox or production;
confirmation that the selected Reteno iOS app matches the selected test environment;
confirmation of which SDK features must be enabled:
- mobile push;
- custom events;
- user identification;
- In-App messages;
- deeplinks;
- custom push data.

Required for iOS push setup and validation

confirmation whether iOS push uses FCM or APNs;
confirmation that Firebase / FCM is configured for the iOS app, if FCM is used;
confirmation that GoogleService-Info.plist belongs to the correct Firebase project, if FCM is used;
confirmation that APNs sandbox / production setup is correct, if APNs is used;
confirmation that push notification capability is enabled or can be enabled;
confirmation that App Groups can be configured, if required;
confirmation that Notification Service Extension can be created or updated, if required;
confirmation that Reteno MCP is connected and available in the AI coding agent environment;
confirmation that the signed-in Reteno account has access to the selected Reteno app/environment;
access to the selected iOS test environment:
- iOS simulator, if supported and confirmed by the developer;
- physical iOS device;
- another supported iOS test environment;
confirmation from the developer that push validation is supported in the selected test environment;
confirmation that push notifications can be enabled in the selected test environment;
confirmation that the developer can open the test push notification if the agent cannot interact with the simulator or device directly.

Required for feature-specific custom event validation

Ask for these inputs when custom event validation is part of the current integration task:

confirmation that a test custom event can be added to the iOS app code;
confirmation that the event name testAiEvent can be used for validation;
access to Reteno MCP, Reteno UI, backend data, event log, or logs to verify that the event was received and assigned to the correct contact.

Required for feature-specific In-App validation

Ask for these inputs when In-App validation is part of the current integration task:

confirmation whether an In-App message already exists or should be created for validation;
existing In-App message name or ID, if an existing In-App message should be used;
confirmation whether the default In-App message is available in the selected Reteno account;
confirmation that the event name eventTestInApp can be used for validation;
access to the selected iOS test environment where the In-App message should appear;
confirmation that the developer, admin, or QA engineer can create, configure, publish, open, or click the In-App message manually if MCP cannot do it.

Required for feature-specific externalCustomerId validation

Ask for these values when the current integration task includes login, registration, user identification, or explicitly asks to validate externalCustomerId:

login or registration flow for externalCustomerId validation;
test login or registration credentials, if required;
expected stable customer ID format for externalCustomerId;
confirmation that the developer, user, or QA engineer can complete the login or registration flow.

Security rules

If credentials or secrets are required, ask the user to provide them through a secure mechanism.

Do not ask the user to paste SDK access keys, Firebase keys, APNs credentials, private keys, certificates, service account data, or other secrets into:

public conversations;
public files;
shared documentation;
source code files that are committed to the repository.

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.

Developer Preparation Checklist

Before starting iOS 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.

1. Project access

The developer should provide or confirm:

access to the iOS 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 .xcodeproj, .xcworkspace, CocoaPods, Swift Package Manager, or another dependency setup;
whether the app uses UIKit / AppDelegate lifecycle, SwiftUI lifecycle, SceneDelegate, or a mixed setup;
whether the app already has Reteno SDK integration;
whether the app already has remote push notification setup;
whether the app already has local notification handling that must be preserved;
whether the app should be validated on an iOS simulator, physical iOS device, or both.

2. Reteno setup

The developer or admin should prepare or confirm:

selected Reteno organization / workspace;
selected Reteno mobile app for iOS;
Reteno SDK access key or approved configuration method for providing it;
whether the selected Reteno mobile app is configured for FCM or APNs;
whether the selected Reteno app matches the iOS bundle ID;
whether the selected Reteno app matches the target environment: development, staging, or production;
whether the selected Reteno app is configured for sandbox or production push 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. Push provider setup: FCM / APNs

The developer should confirm which push provider is used for iOS validation.

If iOS uses FCM, the developer should confirm:

Firebase project is configured for the iOS app;
the correct GoogleService-Info.plist is available;
the iOS bundle ID matches Firebase and Reteno configuration;
Firebase Messaging can be added or is already configured;
the FCM token should be passed to Reteno;
the selected Reteno iOS app expects FCM token type.

If iOS uses APNs, the developer should confirm:

APNs is configured in Apple Developer account;
APNs sandbox / production environment matches the selected test environment;
the app has correct push notification capability;
aps-environment is configured correctly;
the APNs token should be passed to Reteno;
the selected Reteno iOS app expects APNs token type.

The token type in the app must match the token type configured in the selected Reteno mobile app.

4. Xcode project setup

The developer should confirm whether the agent is allowed to modify Xcode project configuration.

This may include:

adding Reteno SDK dependency through Swift Package Manager or CocoaPods;
adding Firebase dependency if FCM is used;
editing project.pbxproj, if needed;
creating or updating AppDelegate;
connecting AppDelegate to SwiftUI lifecycle through @UIApplicationDelegateAdaptor, if the app uses SwiftUI and has no AppDelegate;
creating Notification Service Extension;
configuring App Groups;
enabling push notification capability;
updating entitlements;
adding Reteno dependency to both the main app target and Notification Service Extension target.

If the project has complex signing, targets, or manually managed project settings, the developer should be ready to review or complete Xcode changes manually.

5. Existing notification handling

The developer should confirm what existing notification logic must be preserved.

Check whether the app already has:

UNUserNotificationCenterDelegate;
Firebase MessagingDelegate;
didRegisterForRemoteNotificationsWithDeviceToken;
didReceiveRegistrationToken;
willPresent;
didReceive;
local notification handling;
deeplink handling from push;
custom push actions;
analytics tracking from notification interactions.

The agent must preserve existing notification handlers and add Reteno processing only where required.

If CLICKED status is not tracked after opening a push, the developer should be ready to confirm whether explicit Reteno notification response forwarding is needed.

6. Notification Service Extension and App Groups

For full iOS push delivery tracking and rich push behavior, the developer should confirm:

whether Notification Service Extension already exists;
whether the agent can create a new Notification Service Extension target;
whether App Groups are already configured;
which App Group should be used for Reteno shared storage;
whether the App Group is enabled for both the main app target and the extension target;
whether signing/capabilities allow these changes;
whether the extension target can link Reteno SDK.

If Notification Service Extension or App Groups cannot be configured automatically, the developer should confirm whether they will complete the setup manually in Xcode.

7. Test environment

The developer should prepare one supported test environment:

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

The developer should also confirm:

the app can be built in the selected environment;
the app can be 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 simulator or device directly;
the developer can provide Xcode logs if build/run fails.

Do not assume that a physical iOS device is required if the developer confirms that push validation works in the selected iOS simulator.

8. Reteno 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 simulator or device 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.

If local simulator/device automation is added during the current agent session, the developer may need to restart the agent environment before the tool becomes available.

9. Build and runtime logs

If the agent cannot build or run the app after two attempts to fix the same issue, the developer should provide:

exact build command used;
exact error message;
Xcode logs;
xcodebuild logs, if available;
CocoaPods logs, if dependency setup fails;
Swift Package Manager resolution errors, if package setup fails;
simulator or device details;
crash reason, if available;
reproduction steps.

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

10. 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 iOS 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 required.

If the current integration task includes mobile-push + In-App validation, the developer or admin should confirm:

which In-App message should be attached to the push;
whether Reteno MCP can attach the In-App message to the mobile push in the current environment;
whether the developer/admin can confirm the attachment manually in Reteno UI if required.

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

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

If the current integration task includes deeplinks or custom push data, the developer should confirm:

expected deeplink format;
existing deeplink implementation;
expected behavior for cold start and resumed app state;
expected custom push payload fields.

11. Pre-flight result

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

project access: ready / blocked;
branch: temporary branch created / needs confirmation;
SDK access key handling: ready / placeholder / missing;
Reteno app configuration: confirmed / needs confirmation;
token type: FCM / APNs / needs confirmation;
Firebase / APNs setup: confirmed / needs confirmation;
Xcode project modification permissions: confirmed / needs confirmation;
Notification Service Extension / App Groups: ready / needs setup / not required;
Reteno MCP: connected / unavailable;
local simulator or device automation: available / unavailable;
test environment: ready / unavailable;
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.

iOS SDK Integration Workflow

Follow this workflow for native iOS 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 iOS project

Before making changes, inspect the iOS project.

Identify:

project structure;
dependency manager: Swift Package Manager or CocoaPods;
app lifecycle: AppDelegate / UIKit, SceneDelegate, SwiftUI, or mixed setup;
app target;
bundle ID;
deployment target;
current Reteno SDK usage, if any;
current Reteno SDK version, if installed;
existing push notification setup;
existing local notification setup;
existing UNUserNotificationCenterDelegate;
existing Firebase MessagingDelegate, if FCM is used;
FCM or APNs token handling;
Notification Service Extension;
App Groups;
entitlements;
deeplink handling;
authentication or user identification flow;
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 iOS SDK documentation

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

Use SDK Release Notes to check SDK versions, compatibility notes, migration-related changes, and known fixes.

Use Mobile push error codes when push validation fails and an ERROR status or push error code is available.

3. Check whether Reteno iOS SDK is already installed

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

Instead:

detect the current SDK version from project files;
check how the SDK is initialized;
check whether push notification handling is already configured;
check whether token handling is configured for FCM or APNs;
check whether Notification Service Extension is present;
check whether App Groups are configured;
check whether the current integration is incomplete, outdated, or misconfigured.

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

4. Check prerequisites

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

Check or ask for:

Reteno SDK access key or approved configuration method;
selected Reteno app/environment;
iOS bundle ID;
push provider configuration: FCM or APNs;
GoogleService-Info.plist, if FCM is used;
APNs sandbox / production setup, if APNs is used;
Reteno MCP access;
selected iOS test environment.

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

5. Apply iOS SDK integration changes

Use the official iOS SDK Setup Guide to apply the integration.

Depending on the project, you may need to:

add Reteno SDK dependency through Swift Package Manager or CocoaPods;
add Firebase dependency if FCM is used;
configure SDK initialization;
configure deviceTokenHandlingMode;
configure remote notification registration;
configure FCM or APNs token handling;
configure push notification permission request;
add Reteno processing calls to existing notification handlers where required;
create or update Notification Service Extension;
configure App Groups;
update entitlements;
preserve existing local notification, deeplink, authentication, analytics, and app lifecycle logic.

Do not overwrite existing application logic.

6. Handle iOS app lifecycle correctly

For AppDelegate / UIKit applications, use AppDelegate as the default integration point.

For SwiftUI applications without an existing AppDelegate, create an AppDelegate and connect it to the SwiftUI app entry point through @UIApplicationDelegateAdaptor.

Preserve the existing SwiftUI app lifecycle and do not bypass the existing app entry point.

Create a separate configuration or service class only if:

the project already follows this architecture;
the developer explicitly asks for this structure;
the class is connected to the application lifecycle and does not bypass existing AppDelegate or SwiftUI logic.

7. Configure token handling according to push provider

If the selected Reteno app is configured with FCM:

configure Firebase Messaging;
pass the FCM token to Reteno through the required Reteno token processing method;
do not pass APNs token as the Reteno mobile push token if the selected Reteno app expects FCM.

If the selected Reteno app is configured with APNs:

pass the APNs token to Reteno through the required Reteno token processing method;
do not pass FCM token as the Reteno mobile push token if the selected Reteno app expects APNs.

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

8. Build and run the application

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

Use the selected iOS test environment confirmed by the developer:

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

Do not assume that a physical iOS device is required if the developer confirms that push validation works in the selected iOS simulator.

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

Do not retry indefinitely.

After two unsuccessful attempts to fix the same build, launch, simulator, device, or runtime crash issue, ask the developer to run the app through Xcode or xcodebuild and provide:

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

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

9. Validate the integration with Reteno MCP

After the app builds and runs, validate the integration through Reteno MCP.

Continue with the validation flow:

find the contact;
verify contactId;
verify deviceId, if available;
verify mobilePushToken;
identify token type: FCM or APNs;
confirm that token type matches the selected Reteno iOS app configuration;
send a single-contact test push;
verify DELIVERED;
open the push notification in the selected iOS test environment;
verify CLICKED after the push notification is opened.

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

10. 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 iOS documentation, 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 code, project configuration, dependency setup, entitlements, or supported MCP actions.
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 action, Reteno dashboard changes, Firebase setup, APNs setup, credentials, Apple Developer account access, 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.

11. Return the final report

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

Include:

detected platform and evidence;
iOS project setup;
dependency manager;
SDK version;
files inspected;
files changed;
dependencies added or updated;
Notification Service Extension / App Groups result;
manual steps requested;
manual steps completed;
build/run result;
Reteno MCP connection;
Reteno MCP validation results;
unresolved blockers;
recommended next steps.

Manual Setup Steps

Do not stop when manual interaction is required.

If you cannot complete a step programmatically, ask the developer to perform the required action, wait for confirmation, and then continue the integration or validation flow.

Before requesting manual action, check whether you can complete the step through code changes, project configuration, or available tooling.

1. Complete project-level configuration when possible

If the project setup allows it, complete project-level configuration yourself.

For iOS, this may include:

creating a Notification Service Extension;
configuring App Groups;
enabling required capabilities;
updating Xcode project settings;
adding Reteno dependencies to the main app target and the Notification Service Extension target.

Ask the developer for manual help only if the step requires unavailable signing permissions, certificates, Apple Developer account access, or project-level access that you do not have.

2. Request external push provider setup

Ask the developer to complete external setup when it cannot be done from the codebase.

This may include:

configuring APNs in Apple Developer account;
configuring Firebase Cloud Messaging;
uploading APNs keys, certificates, Firebase keys, or configuration to Reteno;
confirming that the Reteno mobile app is configured with the correct token type: FCM or APNs;
confirming that the selected Reteno mobile app matches the selected test environment: sandbox or production;
creating separate Reteno mobile apps for sandbox and production environments, if both environments are required;
changing app-level push configuration in Reteno dashboard only after developer or admin confirmation.
Continue only after the developer confirms that the external setup is complete.

If Reteno MCP supports app-level setup actions, use them only after explicit developer or admin confirmation.
App-level setup actions may include:

creating a Reteno mobile app;
generating or retrieving an SDK access key;
configuring the app push provider: FCM or APNs;
configuring sandbox or production environment;
uploading APNs keys, certificates, Firebase keys, or configuration to Reteno.

If these MCP actions are not available, ask the developer or admin to complete the setup manually in Reteno dashboard, Apple Developer account, or Firebase console.

Do not create apps, generate keys, upload credentials, or change sandbox / production configuration silently.

3. Run the application

Ask the developer to run the application in the selected test environment.

The selected test environment can be:

an iOS simulator;
a physical iOS device.

Use the environment confirmed by the developer for the current integration or validation run.

Do not assume that a physical iOS device is required if the developer confirms that push validation works in the simulator.

If push validation fails in the selected environment, ask the developer to confirm whether the issue is related to the test environment, push provider setup, Reteno configuration, or another integration problem.

4. Verify local automation permissions, if required

If the AI agent is expected to interact with the simulator, screen, or push notification directly, first verify that the required local automation permissions are granted for the agent or tool.

Depending on the tool and operating system, this may include permissions such as Accessibility, Screen Recording, or Automation.

If the required permissions are not available, ask the developer to perform the interaction manually and continue after confirmation.

5. Screenshot-based push opening fallback

If the agent uses screenshots or visual inspection to understand the iOS simulator/device state, treat screenshots as diagnostic evidence only.

A screenshot can confirm that a push banner, lock screen notification, notification, permission prompt, or button is visible, but it does not guarantee that the agent can tap it.

When validating push click tracking on iOS, use this sequence after DELIVERED is confirmed:

If the push banner is visible, tap the banner.
If tapping the banner shifts it and exposes an Open action, tap Open.
If the notification is visible on the lock screen and exposes Open, tap Open.
If the banner disappears before interaction, open iOS Notification Center and tap the delivered test push notification.
If the agent cannot perform these UI actions, ask the developer or QA engineer to open the test push notification manually.

Do not treat inability to tap the banner, tap Open, open Notification Center, or interact with the lock screen as an SDK integration failure.

Do not retry the same screenshot/tap loop indefinitely.

After the developer or QA engineer confirms that the push notification was opened, continue Reteno MCP validation and verify CLICKED.

Document this situation in the final report as a local simulator/device automation limitation, not as a Reteno MCP failure.

6. Grant push notification permission

When the push notification permission prompt is displayed, ask the developer or user to tap Allow.

Continue only after the permission is granted.

7. Interact with the test push notification

After the test push is sent and DELIVERED status is available, ask the developer to open the test push notification.

After the developer confirms that the push notification was opened, continue validation through Reteno MCP and verify CLICKED status.

8. Complete authentication, if required

If externalCustomerId validation is included in the current scope, ask the developer or user to complete login or registration.

Continue only after authentication is completed.

9. Continue validation

After each manual step is completed:

continue the SDK integration flow;
continue validation through Reteno MCP;
include all completed 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.

Core iOS 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.

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.

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 action;
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 actions are available.

Reteno MCP is not part of the mobile app and is not configured inside the iOS, Android, Flutter, or 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

Cursor direct MCP configuration

For Cursor, add the Reteno MCP server in Cursor MCP settings:

{
  "mcpServers": {
    "reteno": {
      "url": "https://mcp.reteno.com"
    }
  }
}

After saving the configuration, restart Cursor, connect to the Reteno server, sign in with the correct Reteno account, and grant access.

Verify MCP connection

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

Examples:

List the available Reteno MCP tools.

Are any MCP servers connected?

Expected result:

Reteno MCP server is connected;
Reteno MCP tools 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.

Before MCP-based validation, complete the Reteno MCP Setup Quick Check. If Reteno MCP is not connected, document MCP validation as blocked and do not mark the integration as complete.

Validation With Reteno MCP

After applying SDK integration changes, validate the integration through Reteno MCP.

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

Available MCP capabilities

Use Reteno MCP whenever the required MCP actions are available. Before starting MCP-based validation, verify that Reteno MCP is connected in the same environment where you are running. If Reteno MCP is not connected, ask the developer to connect it before continuing with MCP validation.

For iOS mobile push validation, Reteno MCP can:

find a contact by contactId, if this MCP action is available in the current environment;
find a contact by deviceId, if this MCP action is available in the current environment;
display the assigned mobilePushToken;
identify the token type: FCM or APNs;
create a test push notification;
send a test push notification;
verify DELIVERED status;
verify CLICKED status after the developer opens the push notification.

For feature-specific validation, do not assume that all MCP actions are available.
Before using MCP for In-App validation, event validation, or app-level push configuration, check whether the required MCP action exists in the current environment.
For feature-specific In-App validation, Reteno MCP can be used when the required actions are available in the current environment.

In-App MCP actions may include:

find In-App message by name or ID;
get In-App message details by ID or name;
attach an existing In-App message to a mobile push;
verify which In-App message is attached to a push;
get In-App statuses for contact or message: Read, Click, Clicked.

Do not assume that an In-App message already exists in the selected Reteno account.

If the In-App message does not exist and MCP cannot create it, ask the developer or admin to create it manually in Reteno UI or wait until default In-App creation is available for the selected account.

If the action is unavailable, document it as a missing MCP action / requested capability and ask the developer or admin to complete the step manually where possible.
Before validation, check the available Reteno MCP tools/actions. If deviceId lookup is available, use it to confirm that the contact found by contactId matches the expected device.

If a required MCP capability is unavailable, document the limitation as a blocker and continue with the remaining validation steps where possible.

Validation Flow

1. Check Mobile Push Token Configuration

To check which mobile push token type is configured for the mobile app in Reteno, use Reteno MCP when this action is available.
Expected configuration:

iOS: FCM or APNs

Also confirm which Reteno mobile app should be used for the current validation run.
Ask the developer or admin to confirm:

selected Reteno mobile app;
token type configured for the app: FCM or APNs;
APNs environment: sandbox or production;
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 sandbox / production configuration automatically unless this action is explicitly supported and confirmed by the developer or admin.
The token assigned to the contact must match the token type configured for the app in Reteno.

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.
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 application creates or updates the anonymous contact;
- check whether timeZone and languageCode are passed through the 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 the push notification permission request in the app.
If the agent cannot interact with the device directly, ask the user, developer, or QA engineer to accept the permission manually.
Expected result:

The app shows the native push permission prompt;
The permission is granted;
The SDK receives a mobile push token;
The token is sent to Reteno;
The token is assigned to the anonymous contact.

5. Verify mobile push token assignment

After push permission is granted, use Reteno MCP to verify the contact state.
Expected result:

contactId is available;
deviceId is available;
mobilePushToken is available;
osName is available;
token type is available: FCM or APNs.

The token type must match the Reteno app configuration:

iOS contact must have an FCM token if iOS is configured with FCM.
iOS contact must have an APNs token if iOS is configured with APNs.

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 action.
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 there is an ERROR, follow the steps below:

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

Possible causes may include:

Incorrect mobile push token type;
Incorrect Firebase project or Sender ID;
Incorrect APNs configuration;
Sandbox/production mismatch;
Invalid or outdated token;
Incorrect mobile app configuration in Reteno.

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 iOS test environment.

Use the selected iOS test environment confirmed by the developer:

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

Do not stop validation only because the app is running on an iOS simulator. If the developer confirms that push validation works in the selected simulator, continue with simulator validation.

Use this iOS push-opening strategy:

If the push banner is still visible, tap the banner.
If tapping the banner shifts it and exposes an Open action, tap Open.
If the push is visible on the lock screen and exposes Open, tap Open.
If the banner disappears before the agent can tap it, open iOS Notification Center and tap the delivered test push notification there.
If the agent cannot open Notification Center, tap the banner, tap Open, or interact with the selected iOS test environment directly, ask the developer or QA engineer to open the test push notification manually.

Do not repeat screenshot-only checks indefinitely.

Do not treat inability to tap the push banner, tap Open, or open Notification Center as an 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 notification was opened, troubleshoot notification response handling and Reteno push processing calls.

9. Feature-specific validation: Verify push read status

Run READ status validation when it is part of the current integration task or explicitly requested.

After CLICKED status is available, verify whether the push read status is tracked.

Expected result:

READ status is available for the same test push.

If READ validation is required but cannot be completed, document the reason in the final report.

10. 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 the following identifiers

contactId
deviceId
mobilePushToken
messageId
imid
iid
messageTag
Core iOS mobile push validation, verify the following statuses:
DELIVERED
CLICKED
READ
Verify the statuses required for the current integration task.
For core mobile push validation, verify:
DELIVERED;
CLICKED.

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

11. 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 action as a requested capability.

After validating mobile push token assignment and push statuses, verify that custom events are sent through the SDK.
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.
If the event does not appear in the contact activity, check whether segmentation is enabled for this event.

12. 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.

13. Feature-specific validation: Validate In-App message triggered by event

Use this check when the current integration task includes In-App messages or explicitly asks to validate In-App messages.
When In-App messages are included in the integration task, this check is required and must not be skipped.
If the In-App message, MCP action, Reteno UI setup, or selected test environment is not available, document the issue as a blocker, manual step, or missing MCP capability in the final report.

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

Confirm whether an In-App message already exists or should be created for this validation flow.
If an existing In-App message should be used, ask the developer or admin to provide the In-App message name or ID.
If the selected account has a default In-App message, use it only if the developer or admin confirms its name or ID.
Use Reteno MCP to find the In-App message by name or ID.
Use Reteno MCP to get In-App message details.
If the In-App message cannot be found and default In-App creation is not available, ask the developer or admin to create or confirm the In-App message in Reteno UI.
Create or verify a test event named eventTestInApp, if this action is available.
Configure or confirm that the In-App message is triggered after eventTestInApp.
If MCP cannot configure the trigger, ask the developer or admin to complete this step manually in Reteno UI.
Publish or confirm that the In-App message is published and active.
Open the app in the selected test environment.
Send eventTestInApp to the same test contact, if this action is available.
Verify that the In-App message appears in the app.
If possible, click the button in the In-App message.
Use Reteno MCP to verify In-App statuses for the same contact, if status actions are available.

Expected result:

The In-App message is found, created, or confirmed by the developer/admin.
The In-App message details are available.
The event eventTestInApp is received in Reteno, if event validation is included.
The event is assigned to the correct test contact.
The In-App message is published and active.
The In-App message appears in the app.
Status Read is available for the In-App message, if status validation is supported.
Status Click / Clicked is available if the In-App button was clicked and status validation is supported.
The event, In-App message, and statuses belong to the same contact.

Note: If you cannot create, publish, open, or click the In-App message programmatically, ask the user, developer, or QA engineer to complete the required manual step and then continue validation.

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

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

When mobile-push + In-App validation is included in the integration task, this check is required and must not be skipped.

Before attaching an In-App message to a mobile push, verify that the required Reteno MCP action is available in the current environment.

If the action is unavailable, ask the developer or admin to complete the step manually in Reteno UI and document the missing MCP capability.

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

Confirm whether an In-App message already exists or should be created for this validation flow.
If an existing In-App message should be used, ask the developer or admin to provide the In-App message name or ID.
If the selected account has a default In-App message, use it only if the developer or admin confirms its name or ID.
Use Reteno MCP to find the In-App message by name or ID.
Use Reteno MCP to get In-App message details.
If the In-App message cannot be found and default In-App creation is not available, ask the developer or admin to create or confirm the In-App message in Reteno UI.
Create a mobile push message through Reteno MCP, if this action is available.
Attach the existing In-App message to the mobile push message through Reteno MCP.
Verify through Reteno MCP which In-App message is attached to the push.
Send the mobile push message to the test contact.
Verify that push status DELIVERED is available.
Open the push notification in the selected test environment.
Verify that the app opens.
Verify that the In-App message appears.
Click the button in the In-App message, if possible.
Use Reteno MCP to verify In-App statuses for the same contact or message.

Expected result:

The mobile push message is delivered to the test contact.
Push status DELIVERED is available.
The In-App message is attached to the mobile push.
Reteno MCP confirms which In-App message is attached to the push.
The app opens after the push notification is opened.
The In-App message appears after the push interaction.
Status Read is available for the In-App message, if status validation is supported.
Status Click / Clicked is available after the In-App button click, if status validation is supported.
Push, In-App message, and statuses belong to the same contact.

Note: If you cannot create, send, open, or click the mobile-push + In-App flow programmatically, ask the user, developer, or QA engineer to complete the required manual step and then continue validation.

Success criteria

The Reteno SDK integration is successful only when you complete the required validation checks or clearly document a blocker.

Core iOS mobile push validation success criteria

For the iOS push integration flow, the integration is successful when:

you detect the project as an iOS application;
you add and configure the required Reteno SDK integration parts in the selected iOS application;
the app builds and runs successfully;
push notification permission is granted on the selected test environment;
an anonymous contact is created in Reteno;
contactId is available;
mobilePushToken is assigned to the contact;
the mobile push token type matches the Reteno app configuration: FCM or APNs;
you send a test push through Reteno MCP;
push status DELIVERED is available;
the developer opens the test push notification in the selected test environment
push status CLICKED is available after the push notification is opened;
unresolved blockers are documented in the final report.

Feature-specific validation success criteria

Feature-specific validation is required when the current integration task includes the corresponding Reteno SDK feature.

If the integration task includes custom events, In-App messages, mobile-push + In-App, READ status, externalCustomerId, deeplinks, or custom push data, the agent must validate that feature or clearly document why it cannot be validated.

Do not mark a feature as not requested if it was part of the current integration task.

If a feature-specific check cannot be completed, report it as one of the following:

blocked;
manual step required;
missing MCP capability;
unavailable test environment;
unavailable Reteno UI / admin setup.

Blocker handling

Do not report the integration as complete if:

required validation was skipped;
the app does not build;
the test device cannot be used;
Reteno MCP cannot perform a required validation action;
DELIVERED or CLICKED cannot be verified;
the failure reason is unknown or undocumented.

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, and continue with the remaining validation steps where possible.

Recurring SDK issue checks

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

Common recurring issues may include:

missing DELIVERED statuses because Notification Service Extension or App Groups are missing or misconfigured;
FCM/APNs token type mismatch;
mobilePushToken missing after push permission is granted;
APNs sandbox / production mismatch;
SDK version issues or outdated SDK behavior;
In-App issues caused by unsupported SDK version, delayed setup, or missing MCP capability;
unsupported MCP actions required for extended validation.

Use these patterns as troubleshooting hints. Always verify the issue against the current project, official Reteno documentation, MCP results, and logs before applying a fix.

Contact is not found

If Reteno MCP cannot find the contact, check the following:

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

Expected result:

the contact is found by contactId;
the contact has the expected 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 the following:

whether push notification permission was requested;
whether the developer tapped Allow on the permission prompt;
whether the app received a push token;
whether the token was passed to Reteno;
whether the token type matches the Reteno app configuration.

For iOS, verify whether the app uses FCM or APNs.

Expected result:

mobilePushToken is assigned to the contact;
token type is available: FCM or APNs.

Token type does not match Reteno configuration

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

whether iOS is configured with FCM or APNs in Reteno;
whether the app sends the correct token type;
whether Reteno.userNotificationService.processRemoteNotificationsToken is called in the correct place;
whether the app sends an APNs token while Reteno expects FCM, or sends an FCM token while Reteno expects APNs.

Expected result:

iOS contact has an FCM token if Reteno is configured with FCM;
iOS contact has an APNs token if Reteno is configured with APNs.

`DELIVERED` status is missing

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

mobilePushToken;
token type: FCM or APNs;
Reteno mobile app configuration;
FCM or APNs configuration;
Notification Service Extension;
App Groups configuration;
APNs sandbox/production mismatch;
whether push validation is supported in the selected test environment;
push error codes

If there is an ERROR follow the steps below:

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

Possible causes include:

Incorrect mobile push token type;
Incorrect Firebase project or Sender ID;
Incorrect APNs configuration;
Sandbox/production mismatch;
Invalid or outdated token;
Incorrect mobile app configuration in Reteno.

`CLICKED` status is missing

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

whether the test push notification was actually opened;
whether the agent only took screenshots but did not tap the notification;
whether the push banner disappeared before the agent interacted with it;
whether tapping the banner shifted it and exposed the Open action;
whether the agent tapped Open after it appeared;
whether the agent opened iOS Notification Center and tapped the delivered notification;
whether the developer or QA engineer manually opened the test push notification;
whether the app opened after the push notification was tapped;
notification response handling;
Reteno push processing calls.

If the agent cannot open the notification automatically:

Ask the developer or QA engineer to open the delivered test push manually.
Wait for confirmation.
Use Reteno MCP to check CLICKED again.

If the push was opened but CLICKED is still missing, check whether explicit Reteno notification response forwarding is required in the existing notification handler.

Expected result:

CLICKED status is available for the same test push.

Push statuses belong to different contacts or messages

If statuses are found but do not clearly belong to the same test push, verify:

contactId;
mobilePushToken;
messageId;
imid;
iid;
messageTag.

Expected result:

all required statuses belong to the same contact and the same test push.

MCP action is unavailable

If Reteno MCP cannot perform a required validation action:

document which MCP action is unavailable;
continue with the remaining validation steps where possible;
ask the developer or team to confirm the fallback;
include the missing MCP action in the final report as a requested MCP capability;
report the limitation in the final report.

Examples of missing or unavailable MCP actions may include:

creating an In-App message, if default In-App creation is not available;
configuring In-App trigger or display rules;
publishing an In-App message;
retrieving event list / count for a contact;
verifying that an event belongs to the expected contactId / deviceId;
reading app-level push configuration such as APNs sandbox / production setup.

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

Build or run fails

If the app does not build or run, check the following details:

dependency setup;
SDK version;
package manager configuration;
target configuration;
Notification Service Extension dependencies;
Xcode signing or capability issues;
simulator or selected test environment configuration;
runtime crash logs, if available.

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

Do not retry the same fix indefinitely.

After two unsuccessful attempts to fix the same build, launch, simulator, or runtime crash issue, ask the developer to run the app through Xcode and provide:

the exact error message;
crash reason, if available;
relevant Xcode logs;
simulator 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, and what still requires attention.

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 a blocker or not available.

Area	Result
Report type	Complete / Partial
Platform detected	Native iOS
Evidence used for platform detection
Run mode
Application
Git branch / working copy status
iOS bundle ID
Dependency manager	Swift Package Manager / CocoaPods
SDK version
Files inspected
Files changed
Files added
Dependencies added or updated
Notification Service Extension
App Groups
Firebase / FCM configuration
APNs configuration
SDK access key status	Provided / Placeholder / Missing
SDK access key handling
Manual steps requested
Manual steps completed
Build/run result
Test environment
Device automation / simulator automation status
Push opening method	Banner tap / Open action / Notification Center / Lock screen / Manual
Push UI automation result
Screenshot / visual UI check result
Open action detected	Yes / No / Not applicable
Open action tapped	Yes / No / Not applicable
Notification Center fallback used	Yes / No
Manual push open requested	Yes / No
Manual push open completed	Yes / No / Not applicable
Local automation limitation	None / Banner disappeared / Open action not detected / Notification Center unavailable / Manual fallback required
Manual push open requested	Yes / No
Manual push open completed	Yes / No
Runtime validation result
Reteno MCP connection
Reteno MCP validation result
Validation skipped by request	Yes / No
Resume validation from
Contact found
`contactId`
`deviceId`
Contact lookup method	`contactId` / `deviceId`
`mobilePushToken`
Token type	FCM / APNs
Test push sent
Push message identifier, if available
`messageTag`, if used
`DELIVERED` status
`CLICKED` status
Status/contact consistency
Feature-specific validation checks
In-App message name / ID
In-App attachment result
In-App statuses
Missing MCP actions / requested capabilities
Blockers
Recommended next steps

iOS report

For iOS report, include the following details:

whether the project was detected as an iOS application;
whether the integration run used a temporary local branch or copy;
which application was used;
which Reteno integration parts were added or configured;
whether the app built and ran successfully;
whether push notification permission was granted;
whether Reteno MCP found the contact;
whether contactId was available;
whether deviceId was available;
whether Reteno MCP could verify the contact by deviceId;
whether mobilePushToken was assigned to the contact;
whether the token type was FCM or APNs;
whether the token type matched the Reteno app configuration;
whether the test push was sent through Reteno MCP;
whether DELIVERED status was received;
whether the developer opened the test push notification;
whether CLICKED status was received after the push notification was opened;
whether any blocker prevented validation.

Feature-specific validation report

Report each feature-specific validation check according to the current integration task.

Use the following statuses:

not requested for this integration;
completed;
blocked;
manual step required;
missing MCP capability.

If a feature was part of the integration task but could not be validated, do not mark it as not requested. Mark it as blocked, manual step required, or missing MCP capability and explain why.

In-App validation: completed / blocked / manual step required / missing MCP capability / not requested for this integration;
mobile-push + In-App validation: completed / blocked / manual step required / missing MCP capability / not requested for this integration;
testAiEvent: completed / blocked / not requested for this integration;
externalCustomerId: completed / blocked / not requested for this integration.

If any feature-specific validation check was part of the current integration task, report:

whether the check was completed;
which contact was used;
which event, push, or In-App message was used;
whether the result was successfully verified;
any blocker or follow-up action.

If In-App validation is part of the current integration task, report:

In-App message name and ID;
whether the In-App message already existed or was created/confirmed manually;
whether Reteno MCP found the In-App by name or ID;
whether Reteno MCP retrieved In-App details;
whether Reteno MCP attached the In-App to a mobile push, if applicable;
whether Reteno MCP verified which In-App was attached to the push;
whether In-App statuses were received: Read, Click, Clicked;
any missing MCP action or manual/admin step.

Failed validation

If any validation step fails, include:

failed step;
observed result;
expected result;
likely cause, if known;
relevant contactId;
relevant mobilePushToken, if available;
relevant push message identifier, if available;
relevant messageTag, if used;
MCP response or error details, if available;
logs or screenshots requested from the developer, if applicable;
recommended next step.

Blocker reporting

If a blocker prevents the integration or validation from being completed, report:

what is blocked;
why it is blocked;
who needs to resolve it;
whether the remaining validation steps can continue;
what should be done next.

Do not mark the integration as complete if a required validation step failed, was skipped, or could not be verified.

Platform-specific Flows

iOS SDK

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

.xcodeproj;
.xcworkspace;
Podfile;
Package.swift;
AppDelegate;
SwiftUI app entry point.

Use the existing Reteno iOS SDK Setup Guide as the source of truth for iOS-specific installation and configuration steps.

For evaluation, test, or temporary integration runs, use the iOS application selected by the developer.

Integrate the Reteno SDK from scratch into the selected app by following this runbook and the official Reteno iOS SDK Setup Guide.

Use a temporary local branch or copy for temporary integration changes. Do not push or merge these changes.

Choose deviceTokenHandlingMode according to the selected push provider and project setup:

use .automatic for APNs when the SDK can handle APNs token processing automatically and the project does not require custom token handling;
use .manual when the app uses FCM or when the project needs explicit token handling;
for FCM, pass the FCM token to Reteno through Reteno.userNotificationService.processRemoteNotificationsToken;
for APNs manual handling, pass the APNs token to Reteno through Reteno.userNotificationService.processRemoteNotificationsToken.

Before making changes, inspect:

Dependency manager: CocoaPods or Swift Package Manager;
Current Reteno SDK version;
App lifecycle: AppDelegate / UIKit or SwiftUI;
AppDelegate implementation, including SDK initialization and push-related methods;
Reteno SDK initialization, including Reteno.start and deviceTokenHandlingMode, if configured;
Existing push notification setup and push permission flow;
Existing UNUserNotificationCenterDelegate;
Existing Firebase MessagingDelegate, if FCM is used;
FCM or APNs device token handling;
Calls to Reteno.userNotificationService.processRemoteNotificationsToken;
Calls to Reteno.userNotificationService.processRemoteNotificationResponse;
Push notification response handlers, including willPresent and didReceive;
Existing Reteno push processing calls;
NotificationService.swift;
Notification Service Extension;
App Groups configuration;
Any existing custom push, deep link, analytics, or authentication logic that must be preserved.

For iOS push token handling:

if the selected Reteno app is configured with FCM, configure Firebase Messaging and pass the FCM token to Reteno through Reteno.userNotificationService.processRemoteNotificationsToken;
if the selected Reteno app is configured with APNs, pass the APNs token to Reteno through Reteno.userNotificationService.processRemoteNotificationsToken;
do not pass an APNs token to Reteno when the selected Reteno app expects FCM;
do not pass an FCM token to Reteno when the selected Reteno app expects APNs.

For AppDelegate/UIKit applications, use AppDelegate as the default integration point.
Create a separate configuration or service class only if:

the project already follows this architecture;
the developer explicitly asks for this structure;
the class is connected to the application lifecycle and does not bypass existing AppDelegate logic.

If the app uses SwiftUI lifecycle and does not have an existing AppDelegate, create an AppDelegate and connect it to the SwiftUI app entry point through @UIApplicationDelegateAdaptor.
Use the created AppDelegate for Reteno SDK initialization, push notification registration, and mobile push token handling.

Preserve the existing SwiftUI app lifecycle and do not bypass the existing app entry point.

If the project already contains custom push notification handling, preserve the existing implementation and add Reteno processing calls where required.

You may need to update:

Podfile or Swift Package Manager dependencies;
NotificationService.swift;
AppDelegate.swift;
SwiftUI app entry file;
push notification registration code;
device token handling implementation.
Some steps may require manual action, but do not treat all Xcode configuration as manual by default.
If project access and signing configuration allow it, you may complete the following yourself:
create a Notification Service Extension;
configure App Groups;
enable required capabilities;
add the Reteno dependency to the main app target and the Notification Service Extension target.

Ask the developer to complete manual actions only when they require external access or device interaction, such as:

configuring APNs in Apple Developer account;
configuring Firebase Cloud Messaging;
uploading APNs keys, certificates, Firebase keys, or configuration to Reteno;
confirming signing, certificates, or team settings;
running the application in the selected test environment;
accepting the push notification permission prompt;
opening the test push notification.

After completing the iOS-specific setup, continue with the common validation flow, see Validation With Reteno MCP.