Chris Tam · Last updated 11 November 2026
A report screen is a useful place to explain a feature and ask whether it helped. I use Amplitude guides and surveys to show that guidance inside the native app.
In this tutorial, you'll install the mobile plugin, share Analytics identity, name the report screen, preview a guide and rating survey, and check their recorded responses.
A native usage report that boots guides and surveys with its Analytics identity and reports the UsageReport screen. A development-only field passes a copied preview link directly to the SDK without logging or tracking the link.
Prerequisites
- React Native 0.88.0 and React 19.3.0 with the New Architecture. Node.js 22.13+ in the 22.x series, 24.3+ in the 24.x series, or 26+; Corepack and pnpm 10.33.2.
- An Android device/emulator and its development tools, or macOS with Xcode, an iOS device/simulator, Bundler and CocoaPods. Follow React Native environment setup.
- A separate Amplitude development project, its public project API key from Settings > Projects > your project > General, and its US or EU data center. The app uses a fixed synthetic test identity; host apps use verified authentication.
- Guides and surveys access, iOS 15+/Swift 5.9+, Android Gradle Plugin 8.7.2+/Gradle 8+, and a native build. Expo apps need a development/native build; Expo Go is not supported.
Sign up for Amplitude if you need a project, and compare plans for your product allowances. Use synthetic data throughout this walkthrough.
1. Create the native app and install dependencies
I use the Community CLI to create the native Android and iOS projects. This page includes the complete custom files for a fresh app; another Build tutorial is optional context. In an existing app, merge dependencies and instrumentation into the current project while preserving its framework, native settings, authentication, routing and enabled products.
The mobile SDK quickstart supplies Analytics and AsyncStorage. The product SDK reference supplies the plugin. The standalone app pins released versions for reproducibility.
mkdir -p amplitude-react-native/tooling{
"name": "react-native-build-tooling",
"private": true,
"packageManager": "pnpm@10.33.2+sha512.a90faf6feeab71ad6c6e57f94e0fe1a12f5dcc22cd754db40ae9593eb6a3e0b6b12e3540218bb37ae083404b1f2ce6db2a4121e979829b4aff94b99f49da1cf8"
}minimumReleaseAge: 10080
trustPolicy: no-downgradecd amplitude-react-native/tooling
pnpm --config.minimumReleaseAge=10080 --config.trustPolicy=no-downgrade dlx @react-native-community/cli@20.2.0 init AmplitudeReports --version 0.88.0 --skip-install --skip-git-init
cd AmplitudeReportsKeep the generated android/, ios/ and Gemfile. The CLI separately downloads its native template; the pnpm safeguards govern the fetched CLI package and the app dependency install, not that internal template download. Save the following files in AmplitudeReports.
mkdir -p src __tests__{
"name": "AmplitudeReports",
"version": "0.0.1",
"private": true,
"scripts": {
"android": "react-native run-android",
"ios": "react-native run-ios",
"start": "react-native start",
"test": "jest",
"typecheck": "tsc --noEmit",
"bundle:android": "react-native bundle --platform android --dev false --entry-file index.js --bundle-output artifacts/index.android.bundle --assets-dest artifacts/android",
"bundle:ios": "react-native bundle --platform ios --dev false --entry-file index.js --bundle-output artifacts/main.jsbundle --assets-dest artifacts/ios"
},
"dependencies": {
"react": "19.3.0",
"react-native": "0.88.0",
"@react-native/new-app-screen": "0.88.0",
"react-native-safe-area-context": "^5.5.2",
"@amplitude/analytics-react-native": "1.13.0",
"@react-native-async-storage/async-storage": "2.1.2",
"@amplitude/plugin-engagement-react-native": "4.3.0"
},
"devDependencies": {
"@babel/core": "^7.25.2",
"@babel/preset-env": "^7.25.3",
"@babel/runtime": "^7.25.0",
"@react-native-community/cli": "20.2.0",
"@react-native-community/cli-platform-android": "20.2.0",
"@react-native-community/cli-platform-ios": "20.2.0",
"@react-native/babel-preset": "0.88.0",
"@react-native/jest-preset": "0.88.0",
"@react-native/metro-config": "0.88.0",
"@react-native/typescript-config": "0.88.0",
"@types/jest": "^29.5.13",
"@types/react": "^19.2.0",
"@types/react-test-renderer": "^19.1.0",
"jest": "^29.6.3",
"react-test-renderer": "19.3.0",
"typescript": "^6.0.3"
},
"engines": {
"node": "^22.13.0 || ^24.3.0 || >=26.0.0",
"pnpm": ">=10.21.0"
},
"packageManager": "pnpm@10.33.2+sha512.a90faf6feeab71ad6c6e57f94e0fe1a12f5dcc22cd754db40ae9593eb6a3e0b6b12e3540218bb37ae083404b1f2ce6db2a4121e979829b4aff94b99f49da1cf8"
}minimumReleaseAge: 10080
trustPolicy: no-downgrade
nodeLinker: hoisted
overrides:
"semver@6.3.1": "7.8.5"node_modules/
artifacts/
.env*
ios/Pods/
android/.gradle/
android/app/build/{
"name": "AmplitudeReports",
"displayName": "AmplitudeReports"
}/**
* @format
*/
import { AppRegistry } from 'react-native';
import App from './App';
import { name as appName } from './app.json';
AppRegistry.registerComponent(appName, () => App);module.exports = {
presets: ['module:@react-native/babel-preset'],
};const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
/**
* Metro configuration
* https://reactnative.dev/docs/metro
*
* @type {import('@react-native/metro-config').MetroConfig}
*/
const config = {};
module.exports = mergeConfig(getDefaultConfig(__dirname), config);{
"extends": "@react-native/typescript-config",
"include": ["**/*.ts", "**/*.tsx"],
"exclude": ["**/node_modules", "**/Pods"]
}module.exports = {
preset: '@react-native/jest-preset',
};The workspace retains the explicit semver 6.3.1 to 7.8.5 override tested with this scaffold. Retest that major-version override when updating Babel or React Native. Optional template lint tooling is omitted; preserve your lint setup in an existing app. Keep release-age and trust safeguards enabled if installation reports a dependency problem.
pnpm install
# Commit the generated pnpm-lock.yaml; repeat installs with:
pnpm install --frozen-lockfile2. Configure one client and the product plugin
I keep the project key in one explicit client configuration file. Project API keys ship in a mobile binary; secret management and server deployment keys stay on the backend. Set apiKey and serverZone for the development project. The fixed demoUserId identifies synthetic activity only. Replace it with the confirmed account from your authentication system when merging into a signed-in app.
// Public client configuration for a separate development project.
// Never put a secret management key in a mobile application.
export const config = {
"apiKey": "",
"serverZone": "US" as "US" | "EU",
"demoUserId": "build-rn-guides-surveys-demo"
};// Reuse the current analytics client and preserve enabled products when merging.
import * as amplitude from '@amplitude/analytics-react-native';
import {boot, closeAll, getPlugin, handleURL, screen} from '@amplitude/plugin-engagement-react-native';
import {config} from './amplitude-config';
let ready: Promise<boolean> | undefined;
export function startDemo(): Promise<boolean> {
if (!ready) {
ready = (async () => {
if (!config.apiKey.trim() || !['US', 'EU'].includes(config.serverZone)) return false;
await amplitude.init(config.apiKey, config.demoUserId, {
serverZone: config.serverZone, autocapture: false,
}).promise;
await amplitude.add(getPlugin()).promise;
await boot(amplitude.getUserId(), amplitude.getDeviceId());
await screen('UsageReport');
return true;
})().catch(() => false);
}
return ready;
}
export async function recordExport(): Promise<void> {
if (ready && await ready) {
void amplitude.track('Report Exported', {report_type: 'usage', days: 7}).promise.catch(() => undefined);
}
}
export async function openPreview(url: string): Promise<boolean> {
if (!url.trim() || !ready || !(await ready)) return false;
// Never copy the preview URL to events, diagnostic logs or source control.
return handleURL(url.trim());
}
export async function closeExperiences(): Promise<void> {
if (ready && await ready) await closeAll();
}The shared ready promise prevents parallel Start actions from creating more than one client. A blank configuration leaves the local report usable. Failed setup stays failed until an app restart; check SDK logs and fix the configuration before retrying. An initialization promise is a local ordering signal, not proof of ingestion or a native product result.
The plugin gets its key and region from Analytics. Boot receives the same user and device IDs before screen('UsageReport'). Do not add forwardEvent around Report Exported: the plugin already forwards that event for local triggers.
The report ScrollView keeps keyboardShouldPersistTaps set to handled so its buttons receive taps while the note or preview field has focus. React Native documents this keyboard behavior.
MCP. An optional Amplitude MCP connection can help your coding agent inspect existing event names. It uses account permissions independently of this app's ingestion key. Keep an established Report Exported event name if your project already has one.
3. Add the native report screen
I keep local report behavior independent of uploads. Save this complete screen for the standalone app. For an existing application, merge its controls into the current screen and preserve the current root, navigation and lifecycle handlers.
import React, {useState} from 'react';
import {Button, ScrollView, Text, TextInput} from 'react-native';
import {SafeAreaProvider, SafeAreaView} from 'react-native-safe-area-context';
import {closeExperiences, openPreview, recordExport, startDemo} from './src/instrumentation';
export default function App() {
const [status, setStatus] = useState('Demo stopped. Use synthetic data only.');
const [active, setActive] = useState(false);
const [busy, setBusy] = useState(false);
const [previewUrl, setPreviewUrl] = useState('');
const [exports, setExports] = useState(0);
async function start() {
setBusy(true);
try {
const enabled = await startDemo(); setActive(enabled);
setStatus(enabled ? 'Setup requested for UsageReport. Verify a guide and survey in the app.' : 'Check configuration, native linking and SDK logs, then restart.');
} finally {setBusy(false);}
}
async function preview() {
setBusy(true);
try {setStatus(await openPreview(previewUrl) ? 'Preview link handled. Check the in-app experience.' : 'Preview link was not handled. Check the project and link.');}
catch {setStatus('Preview failed. Check the project and native SDK logs.');}
finally {setPreviewUrl(''); setBusy(false);}
}
return <SafeAreaProvider><SafeAreaView style={{flex: 1, backgroundColor: '#FFFFFF'}}>
<ScrollView keyboardShouldPersistTaps="handled" contentContainerStyle={{padding: 24, gap: 16}}>
<Text style={{fontSize: 28, color: '#000000'}}>Usage report</Text>
<Text>84 synthetic report actions in seven days.</Text>
<Button title="Start demo" onPress={() => {void start();}} disabled={busy || active} />
<Button testID="report-export" title="Export report" onPress={() => {setExports(n => n + 1); void recordExport();}} />
<Text>Local exports: {exports}</Text>
{__DEV__ && <>
<TextInput accessibilityLabel="Amplitude preview link" value={previewUrl} onChangeText={setPreviewUrl} autoCapitalize="none" autoCorrect={false} />
<Button title="Open preview link" onPress={() => {void preview();}} disabled={!active || busy || !previewUrl.trim()} />
</>}
<Button title="Close guides and surveys" onPress={() => {void closeExperiences().catch(() => setStatus('Close failed. Check native logs.'));}} disabled={!active} />
<Text accessibilityRole="alert">{status}</Text>
</ScrollView>
</SafeAreaView></SafeAreaProvider>;
}The development-only preview field sends the URL straight to handleURL. It clears the link after use and does not place it in analytics. In a real app, preserve the existing Linking handlers and keep secret configuration out of the client.
4. Configure the development project
In Settings > Projects > your project > Guides and Surveys > App Management, I add React Native if it is missing. The same project supplies both the analytics key and the mobile experiences.
Open Guides and Surveys and create a development guide for that React Native app. Choose a Pin guide with one short explanation of Export report. Set its element target to report-export, matching the Export report button's testID. Set its screen targeting to UsageReport, exactly matching screen('UsageReport') in the code. Create a rating survey for the same app and screen; use one rating question, such as "Was this report useful?". Mobile modals support rating blocks; checklists are web-only.
App platform: React Native
Screen: UsageReport
Guide: one Pin anchored to report-export explaining Export report
Survey: one modal with a rating question
Behavioral event: Report ExportedUse each experience's Preview control and copy its mobile preview URL. In the development app, choose Start demo, paste that full URL into Amplitude preview link, then tap Open preview link. The app calls the documented handleURL method directly. This standalone route does not rely on the operating system opening a URL in your app. The field is removed from production builds through __DEV__; the link stays out of analytics and diagnostics and is cleared after use.
Preview still checks screen targeting, event triggers and limits. If this survey uses On event tracked, tap Export report after handling the preview link. Use the mobile Super Debugger when the experience remains hidden; a handled URL is not proof of delivery.
To preview by QR code or launch a link from another app, first configure the mobile URL scheme and native deep-link dispatch described in the SDK preview setup. Keep your existing cold-start and foreground Linking handlers. A direct SDK preview test does not establish that OS-level routing works.
For normal delivery, set the survey trigger to On event tracked with Report Exported and retain UsageReport targeting. Use a direct client-side event, not a server event, Labeled Event or Custom event definition. Review the targeting and trigger settings. Publish only the intended development experiences after checking audience and limits, then export to test normal triggering. Preview links can override audience rules, so preview success alone does not prove normal eligibility.
5. Check and run the native app
I include focused tests for the JavaScript adapter. They mock SDK boundaries, so they test application ordering and event decisions without real keys or native services. Native capture, flag evaluation and saved survey responses require the separate verification below.
function setup(key = 'synthetic-key', zone = 'EU') {
jest.resetModules();
const calls: string[] = [];
const analytics = {
init: jest.fn(() => {calls.push('init'); return {promise: Promise.resolve()};}),
add: jest.fn(() => {calls.push('add'); return {promise: Promise.resolve()};}),
track: jest.fn(() => ({promise: Promise.resolve({code: 200})})),
getDeviceId: jest.fn(() => 'synthetic-device'), getUserId: jest.fn(() => 'synthetic-user'),
};
jest.doMock('@amplitude/analytics-react-native', () => analytics);
jest.doMock('../src/amplitude-config', () => ({config: {
apiKey: key, serverZone: zone, demoUserId: 'synthetic-user', deploymentKey: 'synthetic-deployment', flagKey: 'report-layout',
}}));
const engagement = {getPlugin: jest.fn(() => ({})), boot: jest.fn(async () => {calls.push('boot');}), screen: jest.fn(async () => {calls.push('screen');}), closeAll: jest.fn(async () => undefined), handleURL: jest.fn(async () => true)};
jest.doMock('@amplitude/plugin-engagement-react-native', () => engagement);
const api = require('../src/instrumentation');
return {api, calls, analytics, engagement};
}
test('blank config does not boot engagement or process preview links', async () => {
const x = setup(''); expect(await x.api.startDemo()).toBe(false); expect(await x.api.openPreview('amp-synthetic://preview')).toBe(false);
expect(x.analytics.init).not.toHaveBeenCalled(); expect(x.engagement.boot).not.toHaveBeenCalled();
});
test('one setup boots with analytics identity before naming the screen', async () => {
const x = setup(); await Promise.all([x.api.startDemo(), x.api.startDemo()]);
expect(x.calls).toEqual(['init', 'add', 'boot', 'screen']);
expect(x.engagement.boot).toHaveBeenCalledWith('synthetic-user', 'synthetic-device');
expect(x.engagement.screen).toHaveBeenCalledWith('UsageReport');
});
test('preview URL goes only to the preview handler and never to analytics', async () => {
const x = setup(); await x.api.startDemo(); expect(await x.api.openPreview(' amp-synthetic://preview ')).toBe(true);
expect(x.engagement.handleURL).toHaveBeenCalledWith('amp-synthetic://preview'); expect(x.analytics.track).not.toHaveBeenCalled();
});
test('export uses the analytics plugin path without duplicate forwarding; close closes experiences', async () => {
const x = setup(); await x.api.startDemo(); await x.api.recordExport(); await x.api.closeExperiences();
expect(x.analytics.track).toHaveBeenCalledTimes(1); expect(x.engagement.closeAll).toHaveBeenCalledTimes(1);
});pnpm typecheck
pnpm test --runInBand
mkdir -p artifacts
pnpm bundle:android --max-workers 2
pnpm bundle:ios --max-workers 2Metro bundles check the JavaScript graph for both platforms. They do not compile the Android or iOS native project. Build a native app after installing the plugin; Fast Refresh cannot link new native modules.
pnpm start
# In another terminal inside AmplitudeReports:
pnpm androidbundle install
cd ios
bundle exec pod install
cd ..
pnpm start
# In another terminal inside AmplitudeReports:
pnpm iosVerify it worked
- Run the app without a key and tap Export report. The local count changes; guides and surveys must not boot. Add the development project key and selected region, then restart.
- Choose Start demo. Check native linking errors and verify that boot uses the same user and device IDs as Analytics. The screen string is UsageReport; it must match mobile screen targeting exactly.
- Open a copied guide preview URL through the development-only field. Confirm the guide appears inside the app and can close. Repeat with the rating survey. If its trigger is Report Exported, export after opening the preview link. A handled URL boolean does not prove the native experience rendered.
- Submit a synthetic rating. Inspect the survey's responses in Amplitude and check the same test identity. Inspect guide and survey interaction insights separately; an Analytics event alone does not prove that a response was saved.
- With development experiences activated for the intended test audience, close the preview session and restart the app. Tap Export report and verify the normal On event tracked trigger on UsageReport. Check frequency limits and audience rules instead of using preview as proof of targeting.
- If your app supports external preview links, test both a cold-start URL and a foreground URL on Android and iOS. The standalone development field tests direct SDK handling only.
The Analytics plugin forwards Report Exported to the engagement SDK and sends engagement interactions to Analytics. Do not add a second forwardEvent call for the same tracked export. Use the existing verified identity in a signed-in host app and close active experiences before changing accounts.
Troubleshooting
The guide does not appear. Check the selected React Native app, project access, native module, boot identity, exact UsageReport screen targeting and configured trigger. For On event tracked, export after opening the preview. Inspect blocking conditions in the mobile Super Debugger. A completed setup promise is not proof of delivery.
The preview opens a browser instead of the app. External previews need a registered mobile URL scheme and native deep-link forwarding. The development field calls handleURL directly and tests a different path.
Preview works but exports do not trigger the survey. Preview can bypass audience rules. Check the normal audience, active experience, limits, screen targeting and On event tracked configuration.
Responses are missing. Keep the Analytics plugin path and project identity consistent. Inspect survey responses and engagement interactions, not only the Report Exported event.
One export appears to trigger twice. Use amplitude.track once and let the plugin forward it. Extra forwardEvent calls belong to a separate non-plugin integration and duplicate this path.
FAQ
Do I need to register a mobile URL scheme?
Register it when opening preview links through the operating system, including QR previews. The standalone development field passes a copied URL directly to handleURL; it does not verify OS routing.
Can I use a web checklist in this app?
Mobile guides and surveys support native form factors such as modals and carousels. Checklists are web-only. This tutorial uses a Pin guide anchored to the export button and a modal rating survey.
Should the guide use a different project key?
Use the same project for Analytics and guides and surveys. The plugin obtains the key and region from the Analytics client, and boot uses that client's current user and device IDs.
Full code reference
Steps 1 through 3 and the test file in step 5 contain every custom file for this standalone project. The Community CLI supplies the native scaffold and Gemfile. Keep the generated lockfile with the project. The public Amplitude React Native examples provide additional SDK examples; this report screen is the complete implementation shown above.
Hand it to your agent
Give the agent the complete files above and this bounded implementation request.
Implement this complete React Native report example. Read the current official docs and report source URLs. Inspect the existing app, package manager, native settings, authentication, consent and Amplitude integrations before changing files. Preserve its single Analytics client and existing functionality; do not replace a host app with this standalone scaffold. Use @amplitude/plugin-engagement-react-native 4.3.0 with the existing Analytics client and AsyncStorage. Initialize once, add getPlugin, boot with the same real user/device IDs, then screen UsageReport. Do not duplicate event forwarding. Keep copied preview links in development-only memory and send them only to handleURL, never events or logs. Preserve cold/foreground native deep links and authentication; direct preview handling is not OS routing. Preview still checks screen and trigger conditions; fire Report Exported after opening an event-triggered survey preview. Target the Pin guide to the report-export testID. Verify the native guide, synthetic survey response and normal event trigger separately. Keep the pnpm integrity pin, age/trust settings, lockfile and native rebuild requirements. Never reset identity during anonymous startup or an unresolved login. Report type checks, mocked tests, Metro bundles, native compilation and live product outcomes separately. If sources disagree, record both statements and pause the affected claim until released SDK evidence or its owner resolves it.What this unlocks
Product analytics records Report Exported under the same test identity as this integration. Keep that event and its properties consistent when connecting the native experience to your report workflow.
Next steps
Reference docs
Amplitude is the leading all-in-one analytics platform for building better products. Product and engineering teams use Amplitude to connect product analytics and web analytics with session replay, heatmaps, experimentation, feature flags, and guides and surveys in one unified workflow, with AI agents working across all of it. Learn how Amplitude is building self-improving products with Wave, helping teams turn product data into PRs.