# Introduction Amply helps mobile teams control and optimize in-app user flows for growth and monetization — without app releases. ## Two audiences, one set of docs These docs serve two audiences. Both read the same pages, but each comes in through a different door. * **Product, growth, and marketing managers** own campaigns and scenarios, work in the dashboard, and read the User Guide, the Concepts pages, and the recipes. * **Engineers** integrate the SDK once and maintain it — they read the Developer Guide and Reference. Every Developer Guide page is written so a non-technical lead can skim it and hand a short brief to their engineer. ## Pick your path [**User Guide**](/user-guide/overview) — for product, growth, and marketing. Set up projects, build campaigns, target users, launch paywall variants, and measure results. Start here if you own the outcome but not the code. [**Developer Guide**](/developer-guide/installation) — for engineers integrating Amply. SDK install, initialization, event tracking, deeplink handling, gating actions, and the REST contract. Start here when you need to wire the SDK into an app. New to Amply? The [Quickstart](/getting-started/quickstart) is the shortest path from zero to a working integration. ## Getting oriented * [What is Amply](/getting-started/what-is-amply) — the problem it solves, the model it uses, and where it stops * [How Amply fits](/getting-started/how-amply-fits) — where it sits in your stack and how data flows * [Changelog](/changelog) — recent releases across dashboard and SDK ## Platforms Amply ships SDKs for iOS, Android, and React Native. All platforms share the same core concepts — events, properties, scenarios, deeplinks — so once you learn Amply on one, the others follow. See [Installation](/developer-guide/installation) for the full requirements matrix. # What is Amply A deeper look at the product: the problem Amply solves, the model it uses, and where it stops. ## The decision layer for in-app experience Most mobile apps run on paid acquisition, multiple ad creatives, Custom Product Pages, subscription monetization, and continuous experimentation. The outside of the funnel is dynamic. Inside the app, experience is usually static. One onboarding for everyone. One paywall screen for everyone. Logic scattered across code and feature flags. Every meaningful change needs a release. Amply closes that gap. It is a decision layer between the context a user arrives with and the experience the app shows them. You configure the decisions remotely, the SDK executes them, and you can change them without shipping a new build. ## Scenarios, not screens Amply is not a screen builder. You build scenarios. A scenario describes: * **When it starts** — which event, attribute, or entry condition triggers it * **Who it applies to** — audience rules over session, device, user, and custom data * **What runs** — the sequence of screens, deeplinks, or actions the app performs * **When it ends** — completion, time limit, or explicit stop Screens and deeplinks are execution details. The scenario is what you own in the dashboard. ## What you can do with Amply These are the cases Amply is built for. **Entry-based onboarding routing.** Different ads and Custom Product Pages lead users to different onboarding screens in your app. Organic users get the default. All routing is configured remotely via deeplink campaigns. **In-app rating prompts at the right moment.** Fire the platform's native rate-review prompt at a specific event and only for users who meet your targeting rules — a successful purchase, a milestone, a positive in-app feedback answer. **Post-trial recovery.** Detect trial end, fire a deeplink campaign that routes to your recovery or offer screen, cap the frequency so users don't see it repeatedly. **Reactivation after inactivity.** Detect that a user hasn't opened the app in N days, route them to a reactivation screen you already have in the app. **Seasonal and event-based campaigns.** Create time-bound campaigns for a holiday or promotion, target the audience, let them deactivate automatically. ## What Amply is not Amply is deliberately narrow. It is not: * A BI dashboard * A push notification platform * A full marketing automation suite * A replacement for RevenueCat * A cross-channel enterprise engagement system * A CMS for in-app content * An A/B testing platform If you need those, keep the tools you use. Amply coordinates with them. ## Who Amply is for Amply is built for teams that actively manage growth and monetization in mobile apps and want to move fast. * **Solo founders** running one or several apps who cannot ship a release every time a paywall needs adjusting. * **Small and mid-size mobile teams** who want remote control over onboarding and paywalls without standing up internal tooling. * **Growth and product managers** who own conversion metrics and need a tool they can operate without a developer in the loop for every change. * **Performance marketing teams** running paid traffic who need the in-app experience to match the ad that brought the user in. If you are an enterprise with omnichannel messaging, cross-device orchestration, and a dedicated customer data platform, Amply is probably not the shape of tool you need. Amply solves a narrower, sharper problem. ## How it works, briefly The SDK runs in your app and collects session, device, and event data. When an event fires or a screen loads, the SDK checks the campaigns you have published. If a campaign matches, the SDK executes its action — opening a deeplink to one of your app's screens, prompting a native rate review, or handing off to your own code. You manage the scenarios in the Amply dashboard. You publish changes from the dashboard. The SDK picks them up on the next session. For the full picture, see [How Amply fits](/getting-started/how-amply-fits). ## How Amply differs from adjacent tools **Versus enterprise engagement platforms.** Enterprise platforms focus on omnichannel messaging, cross-device orchestration, and enterprise data infrastructure. Amply is narrower by design — in-app routing, onboarding orchestration, entry-based flows. If you have a dedicated customer data platform and a large operations team, Amply is not the right shape. **Versus feature flag tools.** Feature flags toggle code paths. Amply orchestrates user-visible campaigns with targeting, triggers, and frequency rules built in. You can use both; they solve different problems. **Versus A/B testing tools.** Amply is not an A/B testing tool — it controls *which scenario a user enters*, not which variant of a widget they see. Use your experimentation tool for the variant test; use Amply for the in-app decision layer around it. **Versus your analytics tool.** Amply has its own event stream for targeting. It is not a BI or product analytics replacement — you should continue to send events to your analytics tool for reporting and exploration. ## A note on scope Amply is built to be lightweight enough for a solo founder to operate and powerful enough to grow with a team. It stays narrow on purpose. When a feature would push Amply into push notifications, BI, or full customer lifecycle management, we say no. The value is in doing one thing — the in-app decision layer — well. ## Related * [How Amply fits](/getting-started/how-amply-fits) — architecture view of where Amply sits in your stack * [Quickstart](/getting-started/quickstart) — get a working integration in under an hour * [User Guide](/user-guide/overview) — build your first campaign * [Developer Guide](/developer-guide/installation) — integrate the SDK # How Amply fits Where Amply sits in your stack, what data it uses, and how a decision travels from a user action to a surfaced experience. ## The three sides Amply connects Amply connects three sides of your app's growth loop. **Acquisition surfaces.** How users arrive: deeplinks, Custom Product Pages, ad campaigns, organic installs, referrals. Each of these carries context Amply can act on — the campaign a user came from, the offer an ad promised, the product page they saw. **App data.** What you know about the user: session data, device attributes, events they have triggered, custom properties you have set (plan tier, trial status, country, anything you track), and subscription state from the tool that owns it. **In-app experiences.** What the app shows: onboarding flows, paywalls, popups, review prompts, deeplinks to specific screens. These are what Amply decides between. Amply is the layer in the middle. It reads the context, evaluates the rules you have published, and tells the app which experience to run. ## Data flow Here is what happens during a session. ``` User opens app │ ▼ SDK starts a session, collects device + session data │ ▼ App calls track("EventName", properties) │ ▼ SDK evaluates published scenarios against current context │ ▼ Matching scenario? ── yes ──▶ SDK runs the scenario's steps │ (deeplink, paywall, action, etc.) │ no ▼ App continues as normal ``` More concretely, the flow is: 1. **Session starts.** The SDK initializes and collects baseline context — device, install date, user properties you have set. 2. **App emits events.** Your code calls `track()` for meaningful moments: onboarding step completed, purchase screen shown, trial started, anything you want to act on. 3. **Scenario evaluation.** The SDK checks the current event against the scenarios published for your app. Rules are evaluated locally using the configuration the SDK has already fetched. 4. **Scenario execution.** If a scenario matches, the SDK triggers its steps. That might be opening a deeplink you handle, showing a screen you have registered, prompting a store review, or firing a callback your app listens to. 5. **Your app responds.** The SDK hands control back to your code to render the actual UI. Amply decides what to show; your app shows it. Scenarios themselves are configured in the dashboard. When you publish a change, the SDK picks it up on the next session — no app release needed. ## What stays where Amply does not try to own every piece of user data. It coordinates with the tools you already run. * **Subscription state** lives in RevenueCat (or whatever you use). Amply reads it through custom properties you set from your app code, or through events you emit when a subscription changes. * **Analytics** stays in your analytics tool. Amply has its own event stream for targeting, but it is not a replacement for product analytics or BI. * **Push notifications** stay with your push provider. Amply triggers in-app experiences, not off-app messaging. * **Your business logic** stays in your app. Amply decides which experience to surface; your code owns the screens and the domain logic behind them. ## Where each audience touches Amply Two audiences interact with Amply in different places. **Product, growth, and marketing** work in the dashboard. They define projects and applications, build campaigns with targeting and triggers, configure scenarios, and watch results. They do not touch the SDK. **Developers** integrate the SDK once. They initialize it with credentials from the dashboard, instrument key events with `track()`, set user properties when they become known (user id, plan, country), and register handlers for deeplinks and scenario actions. After integration, they rarely need to change anything for new campaigns — most campaigns reuse events and deeplinks that already exist. ## What the SDK keeps locally The SDK keeps a small set of local data to make decisions fast and offline-tolerant. * **Session state** — when the current session started and what has happened in it * **Device context** — platform, version, locale, install date, anything collected at first launch * **User identity and custom properties** — whatever you set via `setUserId` and `setCustomProperty` * **Recent events** — a rolling buffer, available for debugging via `getRecentEvents` * **Published scenario configuration** — what to match and what to run, refreshed between sessions None of this is a long-term data warehouse. Analytics, history, and reporting stay in your dedicated tools. The SDK only keeps what it needs to make routing decisions. ## A concrete example A user installs your app from a Custom Product Page tied to a fitness challenge ad. 1. Your attribution provider receives the CPP install and hands the app a campaign identifier. Your code takes that identifier and passes it to Amply as a custom property, e.g. `setCustomProperty("entry_campaign", "fitness_challenge")`. Amply itself does no attribution — it just reads whatever your app sets. 2. The user finishes the app's registration step. Your app calls `track("OnboardingStarted")`. 3. The SDK evaluates scenarios. A scenario targets `entry_campaign = "fitness_challenge"` on `OnboardingStarted` and triggers a deeplink to a fitness-themed onboarding flow. 4. The SDK fires the deeplink; your app handles it and shows the themed onboarding. 5. Later, after a trial ends, another scenario targeting `trial_state = "expired"` fires and shows a recovery paywall variant — one you launched yesterday without releasing the app. Same app binary, different users, different experiences, all configured from the dashboard. ## Related * [What is Amply](/getting-started/what-is-amply) — the product in plain language * [Quickstart](/getting-started/quickstart) — set up a project and send your first event * [Developer Guide](/developer-guide/installation) — SDK integration details * [User Guide](/user-guide/overview) — build campaigns in the dashboard # Quickstart The fastest path from zero to a working Amply integration. Set up a project in the dashboard, then jump to your platform-specific tutorial. **Prefer not to do it by hand?** Use [AI-assisted integration](/getting-started/ai-assisted-integration): connect the Amply MCP and the `amply-integration` skill to your AI coding assistant and have it wire the SDK and hand you a diff to review. You still create the project and application here in the admin — the assistant asks you for the keys. This page is the by-hand path. **Prerequisites** * An Amply dashboard account ([sign in](https://app.amply.tools)) * Your app project on iOS, Android, or React Native **You'll end with** * A project and application created in the Amply dashboard * API keys ready to paste into your app * A clear next step into the platform tutorial that wires the SDK and sends your first event ## 1. Create a project in the dashboard A project groups one or more applications (iOS, Android, etc.) under the same set of campaigns and settings. 1. Open the dashboard. 2. Click **New project** and give it a name that matches your product. 3. Inside the project, click **New application**. Enter a name, set **Platform** to **iOS** or **Android**, and enter your app's **Bundle Id**. Repeat the second step for each platform you ship. ## 2. Get your API keys Open the application you just created and go to the **API Keys** tab. Click **Add Api Key** to generate a key pair. You'll need three values for the SDK: * **App ID** — the application's identifier (visible on the application page). * **Public key** — from the API Keys table. * **Secret key** — from the API Keys table (the value is masked; use the copy button to grab it). Hand all three to whoever wires the SDK into the app — typically your engineer. ## 3. Pick your platform tutorial The next step is platform-specific. Each tutorial installs the SDK, initializes it with the keys from step 2, sends a first event, and verifies it shows up in the dashboard. * [iOS Quickstart](/developer-guide/quickstart-ios) — Swift, UIKit, and SwiftUI. * [Android Quickstart](/developer-guide/quickstart-android) — Kotlin and Gradle. * [React Native Quickstart](/developer-guide/quickstart-react-native) — JS/TS, both Bare and Expo. The concepts are the same across platforms; the API shapes differ. ## What's next After your first event reaches the dashboard: * [Create your first campaign](/user-guide/creating-a-campaign) — act on the event you just sent. * [Set user identity and properties](/developer-guide/user-attributes) — target users more precisely. * [Handle deeplinks from campaigns](/developer-guide/handling-deeplinks) — let scenarios navigate inside your app. ## Related * [How Amply fits](/getting-started/how-amply-fits) — what the SDK does with the events you send * [Installation](/developer-guide/installation) — versions, deployment targets, and package managers per platform * [User Guide](/user-guide/overview) — build and manage campaigns # AI-assisted integration Integrate Amply and build campaigns by directing an AI coding assistant — it does the work, you review the diff. There are two ways to get Amply into your app. You can wire it **by hand** — add the SDK, forward your events, set the attributes you target on (that's the [Developer Guide](/developer-guide/installation)). Or you can let an **AI coding assistant do it for you** — this page. Connect Amply to your assistant and it does the work: it reads your app and sets the SDK up, and it turns a plain-language request into a real campaign. You review and approve; the assistant does the legwork. This doesn't replace the dashboard or the SDK — it's a faster door to both. Developers can still integrate by hand and PMs can still build campaigns in the dashboard. The AI-assisted path is for teams who'd rather describe the outcome and review the result than do every step themselves. ## Set it up Two pieces, set up once. You need an MCP-capable AI assistant (Claude Code, the Codex CLI, or any client that supports MCP). Connecting installs nothing; the skill in step 2 installs either from inside Claude Code, or with the `skills` CLI, which needs [Node](https://nodejs.org). **1. The Amply MCP** — connects your assistant to your Amply account. Amply hosts it, so you point your assistant at a URL: ```bash claude mcp add --transport http amply https://api.amply.tools/mcp ``` Then run `/mcp` in Claude Code and authenticate. A browser window opens, you sign in to Amply, and you approve what the assistant may do — reading your projects, creating draft campaigns, and so on. Amply keeps those permissions separate, so creating a draft can never be the thing that makes it live, but approving is one decision rather than a checklist. You never hand over your password, and you can revoke the connection at any time under **Profile settings → Connected apps**. Any client that supports a remote MCP server over HTTP takes the same URL. See [MCP tools](/reference/mcp-tools) for the full permission list and every tool. {% hint style="info" %} If you used Amply's old local MCP — the `@amplytools/amply-mcp` npm package — it is retired and no longer works. Remove it, connect with the command above, and delete `~/.amply/credentials.json`. {% endhint %} **2. The integration skill (`amply-integration`)** — an open-source playbook that tells the assistant *how* to add Amply well: detect the platform and package manager, audit the analytics the app already has, wire the SDK through a single thin layer, set up the custom properties you'll target on, and verify the build itself. Install it whichever way suits your assistant: {% tabs %} {% tab title="Any assistant (skills CLI)" %} Works with Claude Code, the Codex CLI, and any other host the [`skills` CLI](https://skills.sh) supports: ```bash npx skills add amply-tools/sdk-skill ``` Add `-g` to install for your user instead of the current project. Target a specific assistant with `-a` (e.g. `-a claude-code` or `-a codex`); run `npx skills --help` for the full list of supported assistants. {% endtab %} {% tab title="Claude Code (plugin)" %} Claude Code can install the skill as a plugin from Amply's plugin catalog. Run both commands once, inside Claude Code: ``` /plugin marketplace add amply-tools/claude-plugins /plugin install amply-integration@amply ``` The first command **adds Amply's plugin catalog** — it installs nothing on its own. The second command **installs the skill** from that catalog. (`amply` is the catalog name; `amply-integration` is the skill.) {% endtab %} {% endtabs %} Either path installs the same skill — pick one. Source: [github.com/amply-tools/sdk-skill](https://github.com/amply-tools/sdk-skill) The MCP is the *connection* to your account; the skill is the *know-how* for a clean integration. With both in place you describe the outcome and review the result. ## Integration, the AI way Integrating an analytics-style SDK is usually a checklist a developer works through by hand: install it, find the events the app already fires, forward the ones that matter, and set the user attributes you'll target on. It's mechanical, easy to get subtly wrong, and slow to repeat across apps. > When a developer connects the Amply MCP to their AI coding assistant and asks it to add Amply, the assistant audits the app's existing analytics, installs and initializes the SDK, forwards the events Amply needs for targeting, and sets up custom properties — as a reviewable change in the codebase, not a black box. The developer reads the diff and merges. The result: the same integration a developer would do, produced in one pass and handed back for review — so the judgment stays with you and the typing doesn't. If you granted it the permission to register apps, the assistant does the whole thing: it creates the project, registers the application, takes its `appId` and API key, and writes them into your app's configuration — you never copy a value out of the admin. Without that permission it asks you for those three values instead and carries on from there. Either way the code, the events and the properties are its work. ## Running campaigns by describing them Campaign work normally means a person in the dashboard translating an idea into targeting, a trigger, and an action. MCP lets you state the idea and get the campaign. > When a PM asks the assistant to "show a rewarded-ad gate before export, for free users, once per session," the MCP turns that into a campaign in Amply — audience, trigger, and action wired — for you to review and activate. Checking how an existing campaign is set up works the same way: ask, and it reads it back to you. Common shapes are a single request away — a deeplink when a user's status changes (for example, trial → expired), a prompt after a positive moment, or a paywall on the Nth session. The assistant fills in your audience and trigger and leaves the campaign in Draft for you to review. Two limits worth knowing before you start. The assistant **cannot edit a campaign** — if a draft comes out wrong it will offer you a new one, and you finish or fix it in the dashboard. And on create it can target by country, application, app version and OS version; audiences built on custom properties, install date or event history are authored in the dashboard. You stay in control of what goes live: the assistant proposes, you approve in the dashboard. It compresses the path from idea to live campaign; it doesn't take the decision away from you. ## When to reach for it * **Integrating, or adding Amply to another app** — let the assistant do the SDK pass and hand you a diff. * **Spinning up a campaign quickly** — describe it instead of clicking through the form, then review and activate. * **You'd still use the dashboard** for a careful look before activating, and for anything you'd rather see laid out visually. ## Related * [Quickstart](/getting-started/quickstart) — the by-hand path from zero to a working integration * [User Guide](/user-guide/overview) — building and managing campaigns in the dashboard * [Developer Guide](/developer-guide/installation) — integrating the SDK by hand * [amply-integration skill](https://github.com/amply-tools/sdk-skill) — the open-source playbook the assistant follows # Scenarios and campaigns How Amply separates the product thinking ("what flow should this user get?") from the operational unit you configure in the dashboard ("this campaign, live today, for these users"). ## Scenario — the user flow you want to orchestrate A scenario is the product-level outcome you are trying to produce. It describes what should happen to a user across time: * A new install from a paid ad lands on an onboarding variant matched to the ad. * A user finishes their trial and gets a recovery offer on the next cold open. * A returning user who hasn't opened the app in 10 days gets a winback prompt. Scenarios are how PMs and growth managers think about the work. They have a start, a middle, an end, and a reason. They usually involve more than one thing happening in sequence. Amply does not store a "scenario" object. The scenario lives in your head, in the spec, and on the whiteboard. The dashboard stores the pieces that deliver it. ## Campaign — the primitive you configure in the dashboard A campaign is the unit of delivery. One campaign produces one user-visible outcome (a deeplink opens, the native rate prompt appears) under one set of conditions. A scenario is built from one or more campaigns working together. Every campaign has three parts: * **Who** — targeting conditions that restrict which users are eligible (attributes like country, OS version, app version, install date, custom properties you set on the user). * **When** — a triggering event plus frequency rules (how often, how many times). * **What** — the action to perform when the campaign fires (open a deeplink, show the native rate prompt). See [Targeting and audiences](/concepts/targeting-and-audiences) for the Who, [Campaign delivery](/concepts/campaign-delivery) for the When, and [Campaign actions](/concepts/campaign-actions) for the What. ## Campaign lifecycle A campaign moves between three states: | State | Meaning | | ------ | -------------------------------------------------------------------------------------------------------------- | | Draft | The campaign exists in the dashboard but is not delivered to any device. Use this while you are still editing. | | Active | The campaign is live. Eligible users will see it when its trigger fires. | | Cancel | The campaign is retired. It no longer evaluates on device. | State changes propagate to the SDK on its next configuration fetch. Because campaigns are evaluated from a server-delivered configuration, flipping a campaign to Cancel stops it for every user on their next refresh — no app release needed. See [Campaign delivery](/concepts/campaign-delivery) for the delivery model. ## How campaigns compose into scenarios A scenario is usually not one campaign. It's a handful of campaigns that share audience, track the same signals, and hand off to each other. Example — post-trial recovery scenario: * **Campaign A** detects trial end (triggered by a custom `TrialEnded` event you track) and deeplinks the user to a recovery offer screen on their next session start. * **Campaign B** targets the same users 48 hours later, triggered by `SessionStarted`, and routes to a second, softer offer. * **Campaign C** prompts for an app rating once the user has converted (triggered by `SubscriptionActivated`). Each campaign is simple. The scenario is the pattern across them. ## When to add another campaign vs. widen an existing one Split a campaign when the audience, trigger, or action changes. Keep it as one campaign when you only want to vary volume or cadence. * Two audiences receiving the same deeplink → one campaign, broad targeting. * Same audience receiving different deeplinks depending on a property → two campaigns. * Same audience and deeplink, but one should fire on session start and the other on a custom event → two campaigns. ## Campaign types Amply supports a small, fixed set of campaign types, each producing a specific user-visible action: * **DeepLink campaign** — opens a URL on the device. Route the user to a screen inside your app, or to an external URL. See [Campaign actions](/concepts/campaign-actions). * **RateReview campaign** — presents the platform's native rating prompt (App Store, Google Play). > **On naming.** This documentation uses `DeepLink` and `RateReview` when talking about campaign types as an abstract concept. The dashboard UI labels the same types as **Deep Link** and **Rate & Review** on buttons and tabs. Both refer to the exact same thing. ## Related * [Targeting and audiences](/concepts/targeting-and-audiences) — how the "Who" is built * [Campaign delivery](/concepts/campaign-delivery) — how the "When" is built and how rollout works * [Campaign actions](/concepts/campaign-actions) — the "What" actions * [Creating a campaign](/user-guide/creating-a-campaign) — step-by-step how-to in the dashboard * [Testing and rollout](/user-guide/testing-and-rollout) — how to take a campaign from Draft to Active safely # Sessions and events Amply reasons about users through two units: sessions (when the app was in use) and events (what happened during that use). Everything else — targeting rules, campaign triggers, frequency caps — is built on top of these two ideas. ## What a session is A session is a continuous period of app usage. The SDK starts a session when the app comes to the foreground and ends it when the app goes to the background. A user with ten app-opens across a day has ten sessions. Two kinds of session start: * **Cold start** — the app was launched fresh (not running before). * **Warm start** — the app was already running and returned to the foreground. Short background trips are merged back into the same session rather than starting a new one, so a quick switch to another app and back does not inflate your session count. On each session start the SDK emits the `SessionStarted` standard event. On session end it emits `SessionFinished`. ### Session counter Amply keeps a running counter of how many sessions a user has had. The SDK uses it for delivery and frequency logic. The rule builder doesn't expose session count as a first-class targeting attribute — if you need to target on it, set it as a custom property from your app and reference that in the **Who** step. See [User attributes](/concepts/user-attributes) for how custom properties work, and [Campaign delivery](/concepts/campaign-delivery) for how the counter feeds frequency rules. ## What an event is An event is a named thing that happened inside a session. It has: * A **name** (a short string — `PurchaseCompleted`, `OnboardingStepViewed`). * A **timestamp** (synchronized with Amply's server clock so events from different devices are comparable). * Optional **properties** — a flat map of primitive values that describe the specifics of this occurrence (`plan: "annual"`, `price: 29.99`). Events are what campaign triggers watch for. When an event arrives, the SDK checks every active campaign to see if that event matches the campaign's trigger. ## Standard events vs. custom events Events fall into two buckets. ### Standard events (SDK-emitted) The SDK emits these automatically — session start/finish, config fetch, campaign shown, custom-property changes, and more. You can target and trigger campaigns against them without writing any tracking code. For the complete list with each event's exact properties, see the [Events reference](/reference/events). Standard events have the event type `system` in the dashboard and in triggering rules. {% hint style="info" %} Not every standard event is available as a dashboard trigger today — if you need one for campaign targeting, confirm it appears in the trigger picker before relying on it. {% endhint %} ### Custom events (developer-emitted) Custom events are the ones your app decides to track. They are the vocabulary your product team uses to describe what users do: `OnboardingCompleted`, `PaywallViewed`, `SearchPerformed`, `TrialStarted`. Custom events are recorded through the SDK's `track()` API. The PM picks the name and which properties are useful; the developer wires up the call at the right moment in the app. Plain-English example of how it lands in the dashboard: > When a user fires the `PurchaseCompleted` event with property `plan = "annual"`, and it's their first time this session, open the thank-you deeplink. See [Tracking events](/developer-guide/tracking-events) for how to call `track()` on each platform. ## Properties on events Events carry properties. Properties take primitive values — strings, numbers, booleans. Keep property maps flat; nested objects are not supported. A good property map describes the instance: * `product_id: "sku_123"` * `category: "widgets"` * `price: 29.99` * `source: "search_results"` A campaign trigger can condition on property values: "fire only when `plan = annual`". See [Targeting and audiences](/concepts/targeting-and-audiences) for the condition vocabulary. ## Naming conventions Consistency is more valuable than cleverness. * Event names use `PascalCase`, property keys use `snake_case`. Keep both consistent across all custom events. * Name events as things-that-happened, not screens: `PurchaseCompleted` beats `PurchaseScreen`. * Keep names specific: `OnboardingStepCompleted` with a `step` property is better than `OnboardingStep1Completed`, `OnboardingStep2Completed`, etc. ## Events feed triggers Every event, standard or custom, is available to the rule builder as a **trigger** — "when this event fires, evaluate this campaign". The trigger picker reads from the live Events catalog (see [Sessions and events (user guide)](/user-guide/sessions-and-events)). To target on prior behavior — "users who already did X" — track an event when X happens and **also** set a custom property on the user (for example, `has_completed_onboarding = true`). The rule builder targets on the custom property; the event is what your app sets it from. See [User attributes](/concepts/user-attributes). ## What Amply does not promise about events * Amply is not your primary product analytics tool. It records enough to evaluate rules and power targeting; it does not replace Amplitude, Mixpanel, or PostHog. * Event delivery is best-effort and batched. Exact arrival ordering across devices is not guaranteed. ## Related * [Tracking events](/developer-guide/tracking-events) — how to call `track()` in iOS, Android, and React Native * [Targeting and audiences](/concepts/targeting-and-audiences) — how events become audience rules * [Campaign delivery](/concepts/campaign-delivery) — how standard and custom events drive triggers and frequency * [User attributes](/concepts/user-attributes) — the other half of what Amply knows about a user * [Sessions and events (user guide)](/user-guide/sessions-and-events) — reading the event stream in the dashboard # Targeting and audiences How Amply decides who sees what. A campaign reaches a user only when that user matches the campaign's conditions. This page explains the vocabulary: rules, operators, audiences. ## Rules are built from conditions A rule is a list of conditions you combine in the rule builder. Each condition compares one attribute against one value using one operator. Plain example: > Users whose country is France AND whose `subscription_status` equals `premium` AND who installed the app in the last 30 days. That is three conditions joined with AND. Each condition follows the same shape: ``` country equals France subscription_status equals premium install date is less than 30 days ago ``` You build this in the dashboard's rule builder by adding conditions one at a time. Conditions are joined with AND — every condition must pass for a user to match. Within a single condition, list-style operators give you an internal OR — "country is one of France, Germany, Italy" matches a user in any of the three. ## Attributes you can target on Attributes are grouped by where they come from. See [User attributes](/concepts/user-attributes) for the full picture; here is what you can use in targeting conditions today: * **Country** — the device's country. * **OS version** — the device OS version (for example, iOS 17). * **App version** — the current app version installed on the device. * **App install version** — the version of the app at install time (useful for "only users who installed after v3.0"). * **Application** — which app in your project (include or exclude a specific app). * **Install date** — when the user first installed the app. Works as an absolute date ("installed after 2026-01-01") or a relative one ("installed in the last 7 days"). * **Event history** — what the user has actually done in your app: how many times they've performed an event, whether they've ever done it, and when they first or last did it. Optionally narrowed by event properties ("`Purchase` where `product` equals `pro`"). See [Targeting on past behavior](#targeting-on-past-behavior) below. * **Custom properties** — values you set on the user from your app code (plan tier, premium status, internal user type). For the full list and when to use which, see [User attributes](/concepts/user-attributes). ## Operators The operator set changes slightly by attribute type, but the vocabulary is small. **Numeric and version comparisons:** | Operator | Meaning | | ---------------- | ------------------------ | | equals | exactly equal | | not equal | anything but this value | | greater than | strictly greater | | less than | strictly less | | greater or equal | greater than or the same | | less or equal | less than or the same | **Existence checks:** | Operator | Meaning | | ---------- | --------------------------------------- | | is set | the user has a value for this attribute | | is not set | the user has no value | **List membership (for country, application):** | Operator | Meaning | | -------- | ---------------------------------------------- | | include | match when the user's value is in the list | | exclude | match when the user's value is NOT in the list | **Dates:** Dates support absolute ("on or after 2026-01-01") and relative ("in the last 30 days") forms. Absolute comparisons work in whole calendar days (UTC) — "install date is 2026-01-01" matches any moment during that day. Relative comparisons count rolling 24-hour windows back from now, not calendar days — "in the last 7 days" means the last 168 hours. ## Audience — the result of a rule An audience is the set of users who currently match a rule. It is not a stored list. It is evaluated on-device every time a campaign is considered, using the latest attributes. A user who was in an audience yesterday can drop out today (for example, the user updated to a new app version, or changed country on vacation). This matters: audiences are live. You do not "refresh" or "rebuild" them. A campaign that says "users in France on app version ≥ 5.0.0" will immediately pick up a French user the moment they upgrade. ## Targeting on past behavior Audience rules can target events directly. An **Event** condition matches users by what they have done since installing the app — no extra code, no custom property to maintain. An Event condition can check three things, alone or combined: * **How many times.** "Did `Purchase` at least 3 times", "did `WorkoutCompleted` fewer than 5 times". Operators: exactly, not exactly, more than, fewer than, at least, at most — plus the simple forms **has happened (ever)** and **has never happened**. * **When — first or last occurrence.** Relative: "last `WorkoutCompleted` was more than 14 days ago" (with an explicit "…or never" variant) or "first `Purchase` was within the last 7 days". Absolute: before or after a specific date. Absolute dates cover whole calendar days (UTC); relative "days" are rolling 24-hour windows, not calendar days. * **With matching properties.** Narrow the condition to occurrences whose properties match — "`Purchase` where `product` equals `pro`". Comparisons: equals or not equals; number values also support greater and less. Only matching occurrences count, both for counts and for first/last dates. Event history starts at install, and Event conditions behave like every other condition: evaluated on the device, live, joined with AND, and working offline. {% hint style="info" %} Event conditions require apps built with SDK 0.6.1 or later. On older app builds, a campaign that uses an Event condition simply never matches — nothing breaks, the campaign just stays silent for those users. {% endhint %} ### When a custom property still fits For derived state that isn't a single event — a computed status, a combination of several signals, or something your backend decides — set a custom property on the user and target that instead. The rule builder targets on the property; the event is the trigger that lets your code set it. > When your backend flags an account as at-risk, call `setCustomProperty("account_status", "at_risk")`. A campaign for those users targets `account_status = "at_risk"` — something no single event count could express. Either way, the result is a rich audience composed of attribute, event, and property conditions, all joined with AND. See [Campaign delivery](/concepts/campaign-delivery) for how triggers then decide when the campaign actually fires for those users. ## Targeting vs. triggering These are often confused. * **Targeting** decides who is eligible. "Is this user a match for this campaign?" * **Triggering** decides when the eligible user sees it. "Has the right thing just happened?" A user can be targeted by ten campaigns but only one triggers on any given event. See [Scenarios and campaigns](/concepts/scenarios-and-campaigns) and [Campaign delivery](/concepts/campaign-delivery) for how the two layers interact. ## Practical examples * **"France or Germany, premium users"** — country IN \[France, Germany] AND custom property `plan = "premium"`. * **"New users on the latest app version"** — install date in the last 7 days AND app version >= 3.4.0. * **"Lapsing premium users"** — custom property `plan = "premium"` AND custom property `trial_ends_at` is within the next 3 days. * **"Users who never finished onboarding"** — `OnboardingCompleted` has never happened (or, if you also maintain a property: `has_onboarded` is not set / equals `false`). * **"Repeat buyers"** — did `Purchase` at least 3 times. * **"Lapsed workout loggers — win-back"** — last `WorkoutCompleted` was more than 14 days ago. * **"Never tried export"** — `ExportClicked` has never happened. ## Related * [User attributes](/concepts/user-attributes) — the attributes you can build conditions from * [Sessions and events](/concepts/sessions-and-events) — where event-based conditions come from * [Campaign delivery](/concepts/campaign-delivery) — how triggering combines with targeting * [Targeting an audience](/user-guide/targeting-an-audience) — step-by-step in the dashboard * [User attributes (dev)](/developer-guide/user-attributes) — setting custom properties from app code # User attributes What Amply knows about a user. Attributes come from three places: the device itself, the app install, and what your code tells Amply. Targeting rules, frequency caps, and campaign conditions are all built on top of these. ## Three sources of attributes | Source | Who sets it | Examples | | ----------------- | ---------------------- | --------------------------------------------------------- | | Device attributes | The SDK, automatically | Platform, OS version, country, device model | | App attributes | The SDK, automatically | Install date, app version at install, current app version | | User attributes | You, from app code | User ID, plan tier, premium status, account age | You rarely think about the boundary when you are writing rules in the dashboard — the rule builder shows all three groups together. But it helps to know which is which when you are asking "can I target on this?" Alongside attributes, rules can also target **event history** — how many times an event has happened for a user, and when it first or last happened. That works off the events you already track, with nothing extra to set. See [Targeting and audiences](/concepts/targeting-and-audiences#targeting-on-past-behavior). ## Device attributes — automatic The SDK collects these from the platform. You do not need to write any code. * **Platform** — iOS or Android. * **OS version** — the operating system version. * **Country** — derived from the device locale. * **Application** — which of your apps this is (relevant for projects with more than one app). Device attributes describe the environment. They are good for rolling out a campaign only on one platform, or gating on a minimum OS version. ## App attributes — automatic These describe the install and the usage. * **Install date** — when the app was first installed on this device. * **App install version** — the app version at install time. Useful for distinguishing long-time users from recent installs. * **App version** — the app version currently running. App attributes describe the user's relationship to your app over time. They let you ask "is this a brand-new user or a returning one?", "which cohort did they install into?" > **Note — session count.** The SDK tracks session count internally, but it is not currently exposed as a built-in targeting attribute in the rule builder. To target on session count, set it as a custom property from your app on every session start — see [Sessions and events](/concepts/sessions-and-events). ## User attributes — you set these This is the only group your code controls. There are two calls you need to know: * **`setUserId(userId)`** — attach a stable identifier to this device. Call it when the user logs in. Call it with `null` to clear on logout. * **`setCustomProperty(key, value)`** — store a named value for this user. Call it whenever the value changes. Custom properties take primitive values. The SDK supports strings, numbers, and booleans on every platform. The iOS and Android native SDKs additionally support date/time values. Nested objects and arrays are not supported — keep values flat. Examples of custom properties worth setting: * `plan` — "free", "pro", "team" * `premium` — true / false * `trial_ends_at` — a date * `signup_source` — "organic", "paid\_ads", "referral" * `account_tier` — 1, 2, 3 Custom properties are the bridge between your app's internal state and Amply's targeting. If you want to target "users on the pro plan", someone has to call `setCustomProperty("plan", "pro")` when the user's plan becomes pro. ## When to use which * You want to roll out to a platform or OS → **device attribute**. * You want to gate on "how long have they used the app" → **app attribute** (install date) or a custom property (session count, time-in-app). * You want to gate on a product concept your app owns (subscription state, account type, premium tier, experiment cohort) → **user attribute** (custom property). Rule of thumb: if the value lives inside your app's business logic, it is a custom property. If it comes from the device or the install, the SDK has it for free. ## Identifying the same user across installs `setUserId` is how you keep targeting stable when the user reinstalls, moves devices, or logs in on a second device. The device is what Amply sees by default; `setUserId` gives you a stable handle on top of that. Set the user ID as soon as you have one. Clear it (pass `null`) on logout so the next user on the same device does not inherit the previous user's properties. ## Custom property lifecycle Custom properties persist on the device. Once you set a property, it stays until: * You call `setCustomProperty` again with the same key (overwrite). * You call `removeCustomProperty(key)` (delete one). * You call `clearCustomProperties()` (delete all). * The user uninstalls the app. The persistence means you do not need to re-set properties on every app launch. Set them when they change. ## React to a property changing Targeting on a custom property answers "who is this user *right now*." But sometimes the moment of change is the opportunity. Every time a custom property is set, updated, removed, or cleared, Amply emits a `CustomPropertyChanged` event — and you can use that event as a campaign **trigger**. That means you can react to the instant a trait flips, not just to its current value. For example, fire a winback the moment `plan_tier` becomes `free` — the change itself is the signal, so the campaign runs at exactly the right beat instead of waiting for the next session or event. The event carries the property key plus its old and new value, so a trigger can condition on the direction of the change. See [Events](/reference/events) for the exact parameters. See [Tracking events](/developer-guide/tracking-events) for event tracking, and [User attributes (dev)](/developer-guide/user-attributes) for the exact signatures. ## What is already there vs. what you have to set | Attribute | Automatic? | Notes | | ------------------- | -------------------------- | ---------------------------------------------------- | | Platform | yes | iOS / Android | | OS version | yes | | | Country | yes | derived from locale | | App version | yes | current version | | App install version | yes | the version at install time | | Install date | yes | first install | | Session counter | tracked but not targetable | set as a custom property if you need to target on it | | User ID | no | call `setUserId` on login | | Custom properties | no | call `setCustomProperty` whenever values change | ## Related * [Targeting and audiences](/concepts/targeting-and-audiences) — how attributes become rules * [Sessions and events](/concepts/sessions-and-events) — the other half of what Amply knows * [User attributes (dev)](/developer-guide/user-attributes) — SDK calls in code * [Tracking events](/developer-guide/tracking-events) — complementary: events describe behavior, attributes describe identity # Campaign delivery How an active campaign actually reaches a user. This page covers triggers (what causes a campaign to fire), frequency (how often it can fire for the same user), and rollout (how you take a campaign live safely and roll back instantly if something is wrong). ## The delivery model in one paragraph Amply ships a configuration of active campaigns to each device. The SDK evaluates that configuration locally on every event. When an event matches a campaign's trigger, and the user passes the campaign's targeting, and the frequency rules allow it, the campaign's action runs on the device — an external URL opens, a deeplink routes to one of your screens, or the native rate prompt appears. Because the configuration is delivered from the server, you change campaigns without releasing the app. ## Triggers — what causes evaluation A trigger is an event plus optional conditions on that event's properties. Every active campaign has exactly one trigger. The event can be a standard event emitted by the SDK, or a custom event you call `track()` on. See [Sessions and events](/concepts/sessions-and-events) for the full list. ### Session-start campaigns Set the trigger event to the standard `SessionStarted` event. The campaign is considered every time the user opens the app. Common uses: * Show a paywall on session N. * Reactivate users whose last session was more than 7 days ago. * Route first-time users into an onboarding variant. ### Event-triggered campaigns Set the trigger event to any custom event you track in your app. Common uses: * Trigger a rate prompt after `PurchaseCompleted`. * Open a feature-discovery deeplink after `CoreActionCompleted`. * Show a winback deeplink when `CheckoutAbandoned` fires. ### Event-property conditions on the trigger A trigger can filter on the event's properties. For example, the trigger `PurchaseCompleted` can additionally require `plan == "annual"`. This is separate from audience targeting (which filters on the user). Property conditions filter on the event occurrence. ## Frequency — how often a campaign can fire Amply models frequency in two parts: a repeat rule and a limit. Together they answer "at which occurrences of the trigger should the campaign fire, and what is the overall cap?" ### Repeat rule — which occurrences fire Two repeat modes, applied against either event count or session count: * **Every N** — fire on every Nth occurrence. "Every 3rd session", "every 5th `FeatureViewed`". * **Interval** — fire on specific occurrence numbers from a list. "On sessions 2, 4 and 7" or "on the 1st and 10th `SearchPerformed`". The "entity" picks what you are counting: * **event** — count all occurrences of this event across the user's history. * **session** — count occurrences within the current session only. Plain-English examples: * "Show on every 3rd session from session 3 onwards" — repeat type = every, entity = session, value = 3. * "Show on session 2 and session 5 only" — repeat type = interval, entity = session, value = \[2, 5]. * "Show every 10th `PurchaseCompleted`" — repeat type = every, entity = event, value = 10. ### Limit — the overall cap A limit caps total impressions over a window: * **Count per device or per session** — "at most 3 times, ever" or "at most 1 time in this session". * **Rate limit over a time window** — "at most 1 impression per day", "at most 2 per hour". Limits are evaluated in addition to the repeat rule. Even if the repeat rule matches, the limit can block the impression. ## Rollout controls Rollout is how you take a campaign from "it looks right in the dashboard" to "it is live for everyone" without surprises. ### Audience targeting as rollout The simplest rollout is to narrow the audience. Start active with a tight audience (for example: internal testers identified by a custom property, one country, one app version), verify impressions, then widen by editing the targeting rule. Because targeting is evaluated live, broadening the audience instantly adds users to eligibility; narrowing it instantly removes them. ### State-based rollout Every campaign has a state: Draft, Active, or Cancel. See [Scenarios and campaigns](/concepts/scenarios-and-campaigns) for the lifecycle. * While editing, keep the campaign in **Draft**. No device sees it. * When ready, flip to **Active**. It goes live on every device within moments — no app release. * To stop it, flip to **Cancel**. It stops firing on every device within moments. ### Instant rollback Rolling back a bad campaign is the same as flipping it to **Cancel** in the dashboard — it stops firing on every device within moments. You do not need an app release, a code change, or a feature-flag provider. This is the core promise: in-app behavior is editable without a release. ## Order of evaluation When an event fires on a device, the SDK: 1. Finds every active campaign whose trigger event matches. 2. For each match, evaluates the campaign's targeting against the current user. 3. For each targeted match, evaluates the frequency rules (repeat + limit). 4. Runs the action for the first campaign that passes all three. Only one campaign fires per event. Order your campaigns so that the more specific, more time-sensitive campaigns sit above the fallback ones. ## What happens if the SDK can't reach the server If the device is offline, the SDK uses the most recently fetched configuration. Campaigns already known to the device continue to evaluate. A newly activated campaign on the server reaches the device only on its next successful fetch. For the practical side — previewing before going live, staged rollout, rolling back — see [Testing and rollout](/user-guide/testing-and-rollout). ## Related * [Scenarios and campaigns](/concepts/scenarios-and-campaigns) — the Draft / Active / Cancel lifecycle * [Sessions and events](/concepts/sessions-and-events) — what events you can trigger on * [Targeting and audiences](/concepts/targeting-and-audiences) — the Who layer * [Campaign actions](/concepts/campaign-actions) — what actually runs when the campaign fires * [Testing and rollout](/user-guide/testing-and-rollout) — how-to for safe deployment * [Creating a campaign](/user-guide/creating-a-campaign) — end-to-end dashboard walkthrough # Campaign actions What a campaign does when it fires. Every campaign has a type that determines the action Amply performs on the device at the moment the trigger matches. The set of action types grows over time as new campaign types ship. ## Action types ### Deeplink Routes the user to a screen or URL. When the campaign fires, the SDK calls the deeplink listener your app registered at startup and passes the URL along. Your app handles the routing — the screen you navigate to, how it looks, and what the user does there are all under your control. This is fire-and-forget: Amply sends the URL and the SDK calls your listener; no outcome flows back to the campaign. The URL is a string you control. Two common conventions: * **Your app's own scheme** — for example `yourapp://promo` or `yourapp://feature-discovery`. This is the same scheme you would use for push-notification deeplinks or external launches. Amply routes through it the same way. * **A dedicated scheme for campaign-triggered routes** — the examples in these docs use `yourapp://` as a sample convention (for example `yourapp://campaign/promo/abc123`). This is not a reserved namespace — use whatever scheme or pattern makes sense in your app. A separate scheme can make it easy to distinguish campaign-triggered navigation from ordinary app-wide deeplinks. What a deeplink action is good for: * Routing new users to a specific onboarding screen based on the ad they came from. * Opening a feature-discovery walkthrough after a user completes their first core action. * Showing your paywall screen tied to a specific feature attempt. * Returning lapsed users to a "welcome back" screen with a tailored offer. * Triggering an in-app popup screen you render yourself (the screen is just a route your app already has). In each case, the screen already exists in your app. Amply decides who sees it and when; your app renders it. See [Handling deeplinks](/developer-guide/handling-deeplinks) for the SDK calls on iOS, Android, and React Native, and [Managing deeplinks](/user-guide/managing-deeplinks) for the dashboard side. ### Native rate prompt Triggers the platform's native rating dialog — `SKStoreReviewController` on iOS, the in-app review dialog on Android. This is fire-and-forget: the SDK presents the system prompt and no outcome flows back to the campaign. Both platforms rate-limit and control the prompt tightly; you cannot trigger it at will, and you cannot style it. Use the RateReview campaign type when: * You want the platform's native prompt at a specific moment without any prior custom screen. * The moment is determined by a meaningful event (a successful purchase, a milestone). Gate it carefully with targeting and frequency rules. The platform will suppress prompts shown too often; a campaign that over-prompts will silently stop working on the platform side. For a two-step pattern — first ask the user if they are happy, then route to the native prompt only if they are — fire a custom event such as `PositiveRatingShared` as the RateReview campaign's trigger. See [Rate-review flows](/user-guide/rate-review-flows) for the full pattern. ### Gated action An action that produces an outcome the app waits for before continuing. Instead of fire-and-forget, the app calls `trackGated` at a moment it has registered as a gate; Amply runs the campaign action at that moment and the SDK returns the outcome to the app once the action resolves — for example, after a rewarded ad completes or a user dismisses a prompt. See [Gating an action](/concepts/gating-an-action) for the concept and how to use outcomes in your app flow. ## Related * [Handling deeplinks](/developer-guide/handling-deeplinks) — SDK calls to register the deeplink listener (iOS, Android, React Native) * [Managing deeplinks](/user-guide/managing-deeplinks) — dashboard side for deeplink campaigns * [Rate-review flows](/user-guide/rate-review-flows) — native rate prompt patterns * [Custom popups](/user-guide/custom-popups) — in-app popup pattern via deeplink * [Gating an action](/concepts/gating-an-action) — gated action concept and API * [Campaign delivery](/concepts/campaign-delivery) — triggers and frequency that drive when actions fire * [Scenarios and campaigns](/concepts/scenarios-and-campaigns) — how campaign actions compose into scenarios # Gating an action Some moments in your app are worth pausing for. **Gating** lets a campaign make the app **wait for something to finish** — a rewarded ad, a quick survey, an upgrade screen — before the user's action goes through, and then continue or back out depending on how it went. Most campaigns are fire-and-forget: they fire an action and the app keeps moving. A gate is the opposite — it holds the user's next step until the gated action resolves. ## The two halves * **The app declares the gate-able moments.** A developer marks specific points — "Save", "Export", "Start sync", "Apply filter" — as moments the app is willing to pause at. This is a one-time setup per capability. * **You compose the campaign.** From the dashboard you attach a campaign to one of those moments — its audience, its cadence, and the action it runs — and it starts gating. Pointing the gate at a different moment the app already exposed is a dashboard change, not a release. ## Use cases **Watch a rewarded ad to unlock an action.** A free user taps **Export**. The campaign gates it on a rewarded ad: they watch it through → the export runs; they close it early → the export doesn't happen. You monetize a high-intent moment without a hard paywall. **A one-tap survey before a big step.** Before **Cancel subscription** or **Delete account**, gate on a short reason picker. They pick a reason → the flow continues; they back out → they stay. You capture churn reasons exactly where intent is highest. **A soft upgrade nudge at a premium moment.** A free user taps a pro-only filter. Gate on an upgrade screen: they upgrade → the filter applies; they dismiss → they fall back to the free version. A contextual upsell at the exact point of desire. (Your app still grants the actual entitlement — the gate shapes the moment, see *When not to gate*.) **A value-exchange unlock.** "Invite 3 friends to unlock this theme" — gate the unlock on the invite flow completing, so the reward lands the instant the condition is met. ## When not to gate Gating is for moments where waiting makes sense. Two things should **not** be gated: * **Permission and consent prompts** — tracking permission, privacy consent, push permission. Don't wire these as gates. Show them as ordinary prompts, record the answer as a user attribute for targeting later, and let the user's action continue regardless. Making a core flow wait on a consent answer risks freezing the user on a prompt. * **Opportunistic, informational, or navigational actions** — a rate-and-review prompt, a promo screen, an announcement. These should fire and let the app move on. A simple test: gate it only if "the user deliberately didn't finish this" is a meaningful outcome you'd want to act on. For an ad or a survey, it is. For a consent prompt or a promo, it isn't. ## The safety promise A gate **never traps the user behind a broken dependency.** If the ad fails to load, the network drops, or the app isn't ready, the user's action goes through anyway. The only time an action is held back is a deliberate "the user chose not to complete it" — for example, closing a rewarded ad before finishing — and only when the campaign is set to treat that as a cancel. Because of that promise, **a gate is a UX tool, not a lock.** Don't use it as the thing that grants an entitlement or enforces a payment — grant the premium feature in your app or through the store as you normally would, and use the gate to shape the moment around it. ## What you control without a release Once the app has exposed a gate-able moment, from the dashboard you control: **which campaign gates it, who it targets, how often it fires, what the gated action shows** (for example, a rewarded ad's reward amount or length), and **whether closing it cancels or lets the flow proceed.** Pointing a gate at a different moment the app already exposed needs no release. ## Related * [Handling deeplinks](/developer-guide/handling-deeplinks) — how a developer wires the app's gate-able moments and the action that runs at each * [Tracking events](/developer-guide/tracking-events) — the gate lives at an event the app already tracks * [Campaign delivery](/concepts/campaign-delivery) — how Amply decides which campaign fires at a moment * [Campaign actions](/concepts/campaign-actions) — the fire-and-forget actions a gate sits alongside # Overview A high-level tour of what you can do in the Amply dashboard without writing code. Use this to find the right screen for the task, then click through to the deep page. **Use this when** you're new to Amply and want to know where things live, or when you're orienting a new teammate. **Don't use this when** you already know what you want to do — go straight to the task-specific page. ## Starting point After you sign in, the dashboard is organized around four things, top to bottom: 1. **Projects** — the workspace for an app or a group of apps 2. **Applications** — the individual iOS or Android apps inside a project 3. **Campaigns** — what you actually ship to users 4. **Events** — what users and the SDK report back Billing, team members, and profile settings live alongside these, under the same admin area. ## Projects A project is the container for everything else. Each project has its own applications, campaigns, and event history. Most teams keep one project per product. * **Create or switch project:** project list in the admin area * **Rename, archive, or configure:** project edit screen See: [Dashboard tour — Create your first project](/user-guide/dashboard-tour#create-your-first-project) ## Applications An application represents a shipping app binary — typically one per platform. A project can have several applications (for example, an iOS build and an Android build of the same product). The application is also where the SDK's API key lives. If a developer needs credentials to wire the SDK into an app, you'll generate them here and hand them over. * **List / add / edit applications:** applications screen inside the project See: [Dashboard tour — Add your iOS or Android application](/user-guide/dashboard-tour#add-your-ios-or-android-application) ## Campaigns Campaigns are the main unit of work in Amply. A campaign decides who sees something in the app, when it fires, and what happens when it does — a deep link, a rate-and-review prompt, or a [gated action](/concepts/gating-an-action) the app waits on (like a rewarded ad before an export) before the user's step goes through. From the Campaigns screen you can: * Filter by state: **All**, **Draft**, **Active**, **Cancel** * Create a new campaign via **New campaign** * Open a campaign to view, edit, change state, or delete it A campaign is built in steps: **Who** (audience), **When** (trigger event and frequency), and for Deep Link campaigns, **What** (the URL to open). See: [Creating a campaign](/user-guide/creating-a-campaign), [Campaigns](/user-guide/campaigns), [Targeting an audience](/user-guide/targeting-an-audience) ## Events The Events screen is a catalog of every event name the SDK has seen for this project, across all devices — both SDK-generated events and your own custom events. You'll use it for three things: * Confirming that a new event your engineer just added is actually arriving * Checking when an event was last seen on iOS vs Android * Turning an event on or off for campaign use, per event Events are the raw material for campaign triggers and for audience rules that look at past behavior. See: [Sessions and events](/user-guide/sessions-and-events) ## Team and access Under team settings you can: * Invite teammates to the organization * Manage who has access to which project See: [Dashboard tour — Invite teammates](/user-guide/dashboard-tour#invite-teammates) ## Billing Billing covers your organization's plan, payment method, invoices, and plan upgrades. If you're on a free plan, some advanced features (for example, price management tooling) are hidden until you upgrade. See: [Dashboard tour — Upgrade the plan](/user-guide/dashboard-tour#upgrade-the-plan) ## Price management If your plan includes it, a **Price Management** entry appears in the navigation. Use it to plan, preview, and submit price changes for your in-app subscriptions and one-time products across every country the app sells in — right from the dashboard, no code required. See: [Price management](/price-management/price-management) ## Profile and organization The profile screen holds your personal details and password. The organization screen holds your organization name and org-wide settings. See: [Dashboard tour — Two areas](/user-guide/dashboard-tour#two-areas) ## Recurring tasks Day-to-day work in the dashboard usually involves: 1. Opening **Campaigns** to review what's Active. 2. Creating or editing a campaign — audience, trigger, content — and moving it from Draft to Active. 3. Checking **Events** to confirm the triggering event is arriving from real devices. 4. Adjusting targeting or frequency when a campaign fires too often or too rarely. ## Related * [Creating a campaign](/user-guide/creating-a-campaign) — end-to-end walkthrough * [Targeting an audience](/user-guide/targeting-an-audience) — the rule builder, explained * [Campaigns](/user-guide/campaigns) — campaign types and options * [Sessions and events](/user-guide/sessions-and-events) — what the events screen tells you # Dashboard tour The first 20 minutes after sign-up: create a project, register your app, hand the SDK key to your engineer, build a campaign, and verify it's firing. Each step links to a deeper how-to. **Use this when** you're new to Amply and want a guided path from empty dashboard to first live campaign. **Don't use this when** you already know the workflow — jump straight to [Creating a campaign](/user-guide/creating-a-campaign) or [Price management](/price-management/price-management). ## Two areas The dashboard is split in two: * **Project sidebar** (left) — project-scoped: **Dashboard**, **Campaigns**, **Events**, **Price Management** (gated), **Builder** (gated). Switching projects swaps the contents. * **Avatar menu** (top right) — organization-scoped (**Organization settings**, **Projects**, **Teams & Members**, **Billing**) plus your personal **Profile settings**. Stays the same wherever you are. ## Create your first project A project is the workspace for one product. Create more projects when you need to keep separate apps' data, campaigns, and events apart. 1. From the avatar menu, open **Projects**. 2. Click **New project** in the top right. The form heading reads **Create a new project**. 3. Fill in **Project name** and click **Create Project**. You can switch between projects from the same Projects screen. ## Add your iOS or Android application Each binary you ship is one **application**. A project can hold several — typically one iOS and one Android. 1. From the Projects list, click your project to open it. 2. On the **Applications** screen, click **New application**. Heading: **Create a new application**. 3. Fill in: * **Application Name** — what you'll see in dropdowns later. * **Bundle Id** — the iOS bundle identifier or the Android package name (e.g. `com.example.app`). * **Platform** — **iOS** or **Android**. 4. Click **Create Application**. Repeat for the second platform. Both end up in the same Applications list. ## Hand the SDK key to your engineer Each application has its own pair of API keys (public + secret) that the SDK uses to identify the device and authenticate calls. 1. From the Applications list, click your application to open the edit screen. Heading: **Edit "\"**. 2. Open the **API Keys** tab (third tab, alongside General and Integrations). 3. The table shows **Public key**, **Secret key**, and **Last used**. Each row has a copy icon and a toast confirms when the value is on your clipboard. 4. If the table is empty, click **Add Api Key** in the top right of the page (only visible while you're on this tab). 5. Send the public + secret pair to your engineer. They'll need both for the SDK config — see [Installation](/developer-guide/installation). You can rotate keys later — the row menu offers a **Revoke** action; just generate a new pair first so the SDK never has zero valid keys. ## Create your first campaign A campaign decides who sees something in the app, when it fires, and (for Deep Links) what URL opens. 1. From the project sidebar, open **Campaigns**. 2. Click **New campaign**. The form has two steps for **Rate & Review** (**Who** and **When**) and three steps for **Deep Link** (adds **What**). 3. On the last step, click **Finish**. The campaign saves as **Draft**. 4. Open the new campaign and click **Start campaign** to activate it. Full walk-through: [Creating a campaign](/user-guide/creating-a-campaign). For options each campaign type supports, see [Campaigns](/user-guide/campaigns). A campaign saved as Draft does nothing until you start it. ## Verify it's firing in Events Events is where you confirm the SDK is reporting what you expect — useful both right after wiring up the SDK and after every campaign change. 1. Open **Events** from the project sidebar. 2. The table lists every event name the SDK has reported, with **Last Seen** per platform (iOS / Android icon + timestamp) and an **available** toggle. 3. After you trigger your campaign on a test device, refresh and check that the event row's Last Seen updated. 4. If a custom event isn't in the list yet, the SDK hasn't sent it from any device in this project — trigger it in the app first. The **available** toggle controls whether an event appears in the campaign trigger dropdown — flip it off for noisy or internal events you never want to target. ## Invite teammates To add someone to the organization, open **Teams & Members** from the avatar menu. The screen shows everyone in the org, filterable by **All / Active / Pending / Banned / Rejected** status, with **Name**, **Role**, and **Status** columns. The exact invitation flow depends on how your account was set up — if you don't see an obvious **Invite** action, contact Amply support. ## Upgrade the plan Some features (Price Management, Builder) only appear once your plan includes them. To change plans: 1. Open **Billing** from the avatar menu. 2. On the free plan you'll see the available **plans** alongside your current one. On a paid plan you'll see your current plan and **Invoices**, with an **Upgrade** action that takes you to a separate plan-change view. 3. Pick the new plan and follow the checkout to confirm. After the change goes through, the gated sidebar items become available. ## Related * [Overview](/user-guide/overview) — what each area is for, conceptually * [Creating a campaign](/user-guide/creating-a-campaign) — the next deep dive * [Price management](/price-management/price-management) — if your plan includes it * [Sessions and events](/user-guide/sessions-and-events) — what the Events screen is for * [Installation](/developer-guide/installation) — what your engineer does with the API key # Creating a campaign How to build and ship a campaign from scratch, using the multi-step form in the dashboard. No code required. **Use this when** you want to send users to a specific URL, ask them to rate the app, or (soon) block a flow — based on their behavior. **Don't use this when** you're debugging event delivery or auditing past campaigns — use the [events screen](/user-guide/sessions-and-events) and the campaign list instead. **The faster path:** with [AI-assisted integration](/getting-started/ai-assisted-integration) set up, describe the campaign to your AI assistant in plain language and review the draft it builds — no form-filling. This page is the manual path. ## Before you start You'll need: * A project with at least one application already added * An event name in mind for the trigger (for example, `OnboardingCompleted`, `PaywallViewed`) — either a standard SDK event or a custom event your app already sends * For Deep Link campaigns: the destination URL If the triggering event isn't arriving yet, open the [Events](/user-guide/sessions-and-events) screen first and confirm it's listed for at least one platform. A campaign that listens for an event that never fires will simply never fire. ## Step-by-step {% stepper %} {% step %} ### Open the campaign list From the project, open **Campaigns**. You'll see tabs for **All**, **Draft**, **Active**, and **Cancel**. Click **New campaign** in the top right. {% endstep %} {% step %} ### Name it and pick a type Enter a **Campaign name** — something a teammate will recognize in the list a month from now (for example, `Trial ended — reactivation deep link`). Pick a campaign type: * **Rate & Review** — prompts the user to rate your app using the platform's native review dialog * **Deep Link** — opens a URL in your app or in the browser * **Blocking** — labelled **Soon**; not yet available The type decides what later steps you'll see. Deep Link adds a **What** step for the URL. Rate & Review does not. {% endstep %} {% step %} ### Who — define the audience Start with **All users**. Narrow it down by clicking **Add rule** and picking a condition. Available conditions: * **Countries** — include or exclude a list of countries * **OS Version** — match on operating system version * **App Version** — match on the app version currently installed * **App Install Version** — match on the app version the user originally installed * **Applications** — include or exclude specific applications in the project * **Custom Property** — match on a property you set via the SDK (string, number, boolean, or datetime) * **Install Date** — match on when the user first installed the app, as an absolute date or relative ("less than 7 days ago") Rules combine with **And** — all of them must match. See [Targeting an audience](/user-guide/targeting-an-audience) for patterns and examples. Click **Continue** when the audience looks right. {% endstep %} {% step %} ### When — pick a trigger event and frequency Under **Triggering Event**, choose the event the campaign listens for. The dropdown suggests event names the SDK has already seen in this project. Optionally narrow the trigger further by adding **event parameters** — for example, only trigger when `screen_name` equals `paywall`. Parameters support string, number, and boolean comparisons. Under **Repeat Rules**, choose how often the campaign is allowed to fire for a single user: * **every** N occurrences of the event, **globally** or **in session** * **on** specific occurrences (1st, 3rd, etc.) Under **Frequency Limits**, cap how often the campaign can fire overall per session or per device, optionally over a time window (seconds, minutes, hours, or days). Click **Continue**. {% endstep %} {% step %} ### What — set the content (Deep Link only) If you picked **Deep Link**, enter the **DeepLink** URL the campaign should open when it fires. This can be: * A regular `https://` link to open in the browser or in-app browser * A custom scheme (for example, `yourapp://promo/spring`) your app already handles For **Rate & Review**, there's nothing to configure — the platform's native review prompt is shown. Click **Finish** to save the campaign. {% endstep %} {% step %} ### Activate it A new campaign saves as **Draft**. From the campaign list or the campaign's detail screen, change its state to **Active**. Only Active campaigns evaluate against live traffic. To pause a campaign, switch its state to **Cancel**. It stops firing immediately for new events. {% endstep %} {% endstepper %} ## After you ship Spot-check the campaign in the first hour: * Open the campaign from the list and check that the state is **Active** * On a test device, reproduce the triggering event and confirm the deep link opens or the review prompt appears * In [Events](/user-guide/sessions-and-events), confirm the triggering event is arriving from real devices — not just your test How the app actually receives the deep link depends on the SDK integration. See the developer-guide pages for platform-specific listener setup: [Android](/developer-guide/android-integration), [iOS](/developer-guide/ios-integration). ## Common mistakes * **Campaign saved as Draft and forgotten.** Draft campaigns don't fire. Flip to Active. * **Triggering event name typo.** Pick from the dropdown whenever possible. If you type a name by hand, copy-paste from the event catalog. * **Audience too narrow.** If nothing fires for a day, loosen the rules and re-test. * **Rate & Review in a debug build.** On Android, the Play Store review prompt only appears in release builds distributed through Play. Debug shows a simulated dialog. ## Related * [Targeting an audience](/user-guide/targeting-an-audience) — patterns for the Who step * [Campaigns](/user-guide/campaigns) — campaign types and the options each one supports * [Sessions and events](/user-guide/sessions-and-events) — confirm your trigger event is arriving * [Campaign delivery](/concepts/campaign-delivery) — how a campaign evaluates against an event # Campaigns The dashboard campaign reference: how the list view is organized, the per-type options each campaign exposes, and the When-step mechanics for repeat rules and frequency limits. > Reference for the dashboard. For the model — what a campaign is, how it composes into a scenario, the lifecycle — see [Scenarios and campaigns](/concepts/scenarios-and-campaigns). For step-by-step creation, see [Creating a campaign](/user-guide/creating-a-campaign). ## The campaign list Open **Campaigns** in a project. The list shows every campaign in any state and offers four filter tabs: * **All** * **Draft** * **Active** * **Cancel** Open a campaign to view, edit, change state, or delete it. The new-campaign action is **New campaign** at the top right. What you can do per state: | State | State-change button on the detail screen | Other actions | | ------ | ---------------------------------------- | ------------- | | Draft | **Start campaign** (moves to Active) | edit, delete | | Active | **Stop campaign** (moves to Cancel) | edit | | Cancel | **Start campaign** (re-activates) | edit, delete | A state change propagates to every device on the next configuration fetch — see [Campaign delivery](/concepts/campaign-delivery). ## Campaign types and their options ### Rate & Review Prompts the user to rate your app using the platform's native review dialog — the App Store review prompt on iOS, the Play Store in-app review on Android. Use it for: * Asking satisfied users to leave a review after a positive moment (completing a purchase, finishing onboarding, earning an achievement). Options the form exposes: * **Who** — audience rules. See [Targeting an audience](/user-guide/targeting-an-audience). * **When** — triggering event, optional event-parameter filters, repeat rules, frequency limits. * No **What** step — the platform dialog is fixed. Notes: * On Android, the Play Store's in-app review API only produces a real prompt in release builds distributed through Play. Debug builds show a simulated dialog. * The platforms cap how often the prompt actually shows, regardless of your repeat rules. Treat "asked" as best-effort. ### Deep Link Opens a URL when the campaign fires. The URL can be: * A standard `https://` link (opens in the browser or an in-app web view, depending on how the app handles it). * A custom URL scheme (for example, `yourapp://promo/spring`) handled by your app's deep-link code. Use it for: * Routing users into a specific in-app screen (paywall, offer, onboarding variant, feature tour). * Sending users to a web destination (blog post, survey, support article). * Triggering an in-app flow that's already wired up to a scheme your app owns. Options the form exposes: * **Who** — audience rules. * **When** — triggering event, event parameters, repeat rules, frequency limits. * **What** — the **DeepLink** URL to open. For the URL to do anything useful, your app needs a deep-link handler registered via the SDK. See [Android integration](/developer-guide/android-integration) and [iOS integration](/developer-guide/ios-integration). ### Blocking Marked **Soon** in the dashboard. Not available yet. ## The When step — repeat rules and frequency limits Every campaign is triggered by an event. The When step lets you control how often a single user is eligible to see it, beyond the audience filter. **Triggering Event.** Pick an event name — system events like `SessionStarted` or any custom event your app sends. Optionally filter by **event parameters** ("only when `screen_name` equals `paywall`"). **Repeat Rules.** How often the campaign is allowed to fire for one user: * **every** N events — "every 3rd purchase". * **on** the Nth event — "on the 1st purchase only". Scope: **globally** (across sessions, across time) or **in session** (this session only). **Frequency Limits.** Overall caps, independent of the repeat rules: * Per **session** — at most N times in a single session. * Per **device** — at most N times per device, optionally over a window (seconds, minutes, hours, or days). A campaign that fires too often is almost always a repeat-rules or limits problem, not a targeting one. ## Choosing a type — quick table | Goal | Type | | -------------------------------------------------- | -------------------------- | | Ask users to rate the app | Rate & Review | | Open a paywall variant in-app | Deep Link (custom scheme) | | Send users to a web offer or survey | Deep Link (`https://`) | | Route marketing cohorts into different onboardings | Deep Link (custom scheme) | | Block a flow until something happens | (Blocking, when available) | ## Related * [Scenarios and campaigns (concepts)](/concepts/scenarios-and-campaigns) — what a campaign is and how it fits a scenario * [Creating a campaign](/user-guide/creating-a-campaign) — step-by-step walk-through * [Targeting an audience](/user-guide/targeting-an-audience) — the Who step in depth * [Sessions and events](/user-guide/sessions-and-events) — events the When step can listen for * [Campaign delivery](/concepts/campaign-delivery) — how a campaign is evaluated # Targeting an audience How to narrow a campaign from "everyone" down to the right slice of users, using the rule builder in the campaign form's **Who** step. > Dashboard walkthrough. For the targeting model and the attributes you can target, see [Targeting and audiences](/concepts/targeting-and-audiences). **Use this when** a campaign should only apply to some users — a country, an app version, users who installed recently, users who did (or never did) something in your app, or users who match a property you control. **Don't use this when** you want to control *when* a campaign fires (that's the **When** step and the triggering event) or *what* it shows (that's the **What** step). ## Where to find it Audience rules live in the **Who** step of the campaign form: 1. Open a project → **Campaigns** → **New campaign** (or open an existing draft). 2. Fill in the name and type in step one. 3. On the **Who** step, start from **All users** and click **Add rule**. Every rule you add narrows the audience. Multiple rules combine with **And** — a user must match all of them. There is no "or" between rules; if you need an either/or audience, make two separate campaigns. ## Rule types and operators Each rule lives in its own card. Add, edit, or remove rules in any order. | Rule | Operators | Example | | --------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------- | | **Countries** | include / exclude one or more countries | Include **Germany, France, Spain** | | **OS Version** | `=`, `!=`, `>`, `<`, `>=`, `<=` | `>=` `17` (iOS 17 and up). Add twice for a range. | | **App Version** | same as OS Version | `>=` `4.2.0` | | **App Install Version** | same as OS Version | `>=` `3.0.0` and `<` `4.0.0` (twice) | | **Applications** | include / exclude one or more applications in the project | Include the iOS build only | | **Custom Property** | depends on the value type — see below | `tier` `=` `premium` | | **Install Date — absolute** | is, is before, is after | "is after 2026-01-01" | | **Install Date — relative** | is less than N days, is more than N days | "is less than 7 days" | | **Event** | count of times done, first/last occurrence date, optional property filters — see below | `Purchase` at least **3** times | Custom Property operators by value type: | Type | Operators | | -------- | --------------------------------------------------- | | String | `=`, `!=`, is set, is not set | | Number | `=`, `!=`, `>`, `<`, `>=`, `<=`, is set, is not set | | Boolean | `=`, `!=`, is set, is not set | | DateTime | is, is before, is after, is set, is not set | **Is set** and **is not set** check whether the property exists on the user at all — they don't need a value. Property keys are suggested from what the SDK has reported for this project; pick from the dropdown to avoid typos. ## Adding an Event condition Target users by what they have done in your app — how often, and when. {% hint style="info" %} Event conditions require apps built with SDK 0.6.1 or later. On older app builds, a campaign that uses an Event condition never matches — it fails safely and silently. {% endhint %} ![Event conditions in the Who step: counts, occurrence dates, and property filters](/files/8iMAizsJDkkEM6tNubkz) 1. On the **Who** step, click **Add rule** and choose **Event**. 2. Pick the event — for example `Purchase` or `WorkoutCompleted`. 3. Choose what to check: * **How many times** — exactly / not exactly / more than / fewer than / at least / at most **N** times, or simply **has happened (ever)** / **has never happened**. Counts cover the lifetime of the install. * **First occurrence** or **Last occurrence** — relative ("more than **14** days ago", with an "…or never" variant that also matches users who never did it; "within the last **7** days") or absolute ("before" / "after" a date). Absolute dates cover whole calendar days (UTC); relative days are rolling 24-hour windows, not calendar days. 4. Optionally add **property filters** — type a key and value, compared with equals or not equals (number values also support greater / less). `Purchase` with `product` equals `pro` counts only pro purchases: occurrences that don't match the filters are ignored for both the count and the first/last dates. Like every other rule, Event conditions combine with **And**, are evaluated live on the device, and work offline. Event history starts when the app is installed. A campaign can have up to 20 Event conditions. ## Worked examples ### Paying users on iOS 17+ in Germany 1. **Custom Property** — `subscription_status` `=` `active` 2. **Countries** — include **Germany** 3. **OS Version** — `>=` `17` (and consider filtering by application for iOS-only) ### New users on the latest app version 1. **Install Date** — is less than **14** days ago 2. **App Version** — `>=` `5.0.0` ### Everyone except early adopters on old builds 1. **App Install Version** — `>=` `4.0.0` 2. **App Version** — `>=` `5.0.0` ### Power users with a specific flag 1. **Custom Property** — `lifetime_purchases` `>=` `5` 2. **Custom Property** — `beta_opt_in` is set ### Win back lapsed workout loggers 1. **Event** — last `WorkoutCompleted` occurrence more than **14** days ago 2. **Install Date** — is more than **30** days ago (so brand-new users don't get a win-back message) ### Repeat pro buyers 1. **Event** — `Purchase` at least **3** times, with property filter `product` `=` `pro` ## Tips * **Start broader than you think.** A too-narrow audience that matches almost nobody looks the same as a broken campaign. Widen, confirm it fires, then tighten. * **Name custom properties consistently.** Amply's convention is `snake_case` for property keys (and `PascalCase` for event names). The dropdown shows exactly what the SDK reported — match whatever your developer set up. * **If a property isn't in the dropdown,** the SDK hasn't sent it yet from any device in this project. Trigger it on a test device first. * **Country rules use device region, not IP.** A user travelling abroad still counts as their device's region. * **Install date reflects the first install Amply saw.** Uninstall and reinstall resets it. ## Related * [Targeting and audiences (concepts)](/concepts/targeting-and-audiences) — the model behind rules and attributes * [Creating a campaign](/user-guide/creating-a-campaign) — full walk-through of the campaign form * [Sessions and events](/user-guide/sessions-and-events) — confirm your custom property is arriving * [User attributes](/developer-guide/user-attributes) — how developers set custom properties from the SDK # Managing deeplinks A deeplink campaign sends a user to a specific place in your app at a moment you choose. You pick who sees it, what triggers it, and which URL the app receives. Your engineering team decides what that URL opens. **Use this when** you want to steer users to a specific screen, paywall, or flow in response to in-app behavior — without shipping a new app version. **Don't use this when** you only need to show a message. A native rate-and-review prompt or a custom popup is a better fit for that. ## Before you start * The mobile team must register a deeplink listener in the app once. See [Handling deeplinks](/developer-guide/handling-deeplinks). * Agree on a URL convention across product and engineering (for example, `yourapp://paywall/annual`). The dashboard stores whatever you type; the app decides how to parse it. * Have at least one event available in the project that represents the moment you want to react to. Custom events come from `Amply.track(...)` calls in the app; system events (like `SessionStarted`) are available by default. ## Create a deeplink campaign 1. Open **Campaigns** in the project sidebar and click **New campaign**. 2. Enter a **Campaign name** the team will recognize. Choose type **Deep Link**. 3. **Who** — pick the audience for the campaign. You can combine: * **Countries** (include or exclude) * **OS Version** (compare against a value) * **App Version** / **App Install Version** * **Applications** (if the project has more than one) * **Custom Property** (any user attribute you set from the SDK) * **Install Date** (absolute or relative) Leave the section empty if you want to target everyone in the project. 4. **When** — choose the **Triggering event**. Add event parameter filters if you want only a subset of fires (for example, `source == "home"`). Configure **Repeat Rules** (every N events, or at specific session counts) and **Frequency Limits** if you want to cap how often a single user sees the campaign. 5. **What** — enter the **DeepLink** URL that should be passed to the app. Example values: * `yourapp://paywall` * `yourapp://feature-discovery?variant=v2` * `yourapp://onboarding/step3` 6. Save. The campaign is created in **Draft** state. ## When a deeplink fires Amply evaluates campaigns every time an event is tracked. For each campaign: 1. The **Who** conditions are checked against the current user. 2. The **When** conditions are checked against the event being tracked. 3. If both match, the campaign is eligible to fire. 4. Frequency limits are applied. If the user is under the cap, the deeplink URL is sent to the mobile SDK. 5. The SDK calls the deeplink listener your engineers registered. They decide what screen to open. Only campaigns in **Active** state are evaluated. **Draft** and **Cancel** campaigns are ignored. ## Activate, pause, or cancel Campaign state is changed from the campaign list or the campaign detail page. * **Draft → Active** — starts delivery. No app release required. * **Active → Cancel** — stops delivery immediately. No app release required. * Cancelled campaigns can be returned to Active or duplicated into a new draft. Changes propagate to installed apps on the next campaign sync. For most flows this is the next session start. {% hint style="info" %} You can change the **What** URL on an Active campaign. Every session started after the change receives the new URL. Existing sessions keep the URL they already fetched. {% endhint %} ## Test a deeplink from a staging build The goal is to verify that (a) your campaign is eligible for your account, and (b) the app handles the URL correctly once received. 1. Install a staging or development build of the app that is wired to the same Amply project as the campaign. Your mobile team sets this up during integration. 2. Make sure your device matches the campaign's **Who** conditions. If you narrowed by country or a custom property, either widen the conditions for the test or set the matching property from the app. 3. Fire the **Triggering event** from the app. For a custom trigger like `PaywallShown`, you trigger it by doing whatever action the code hooks into. 4. Watch the deeplink listener in the app's logs. The URL you typed in **What** should arrive with the campaign metadata. 5. Confirm the app opens the expected screen. If nothing fires, walk through the checklist in [testing-and-rollout.md](/user-guide/testing-and-rollout#troubleshooting). ## Worked example — onboarding feature discovery Goal: show a feature-discovery screen to users on their third session who have not used the feature yet. * **Who**: Custom Property `used_feature_x` is not set (or equals `false`). * **When**: event `SessionStarted`, repeat every session, frequency limit "1 time per device". * **What**: `yourapp://feature-discovery?feature=export-pdf`. Your app's deeplink handler reads `feature=export-pdf` and opens the corresponding screen with a tooltip. ## Common patterns | Pattern | Trigger | URL shape | | -------------------------------- | ---------------------------------------------- | ----------------------------------------- | | Paywall on deep session | `SessionStarted`, every 3rd session | `yourapp://paywall/annual` | | Winback after gap | `SessionStarted`, audience filter on last-seen | `yourapp://welcome-back?offer=50` | | Feature wall | `FeatureClick` with `feature == "pdf_export"` | `yourapp://paywall/feature?id=pdf_export` | | Invite prompt at positive moment | `PositiveMoment` event | `yourapp://invite-friends` | ## Related * [Handling deeplinks](/developer-guide/handling-deeplinks) — the developer side: registering a listener and routing the URL. * [Campaign actions](/concepts/campaign-actions) — when to pick one action type over another. * [Testing and rollout](/user-guide/testing-and-rollout) — how to validate a campaign before it goes to all users. * [Campaigns](/user-guide/campaigns) — full reference on campaign structure. # Rate & review flows The native app-store review prompt is limited and unforgiving: each store caps how often it can appear, and a badly-timed prompt can surface a frustrated user and a one-star review. This page covers how to gate that prompt behind a positive moment and an audience filter so the users who see it are the ones most likely to leave a five-star rating. **Use this when** you want more positive ratings and fewer negative ones — and you have an in-app moment that reliably signals the user is happy (a completed task, a milestone, a successful purchase). **Don't use this when** you have no way to detect a positive moment. Asking at session start or after a generic screen view hurts your rating more than it helps. ## The idea A naive Rate & Review campaign runs on every session and prompts anyone the store allows. You get ratings from whoever happens to be around — including users mid-frustration. A gated Rate & Review campaign only fires after a signal that the user is in a good state. That signal is just an event your app already tracks. You use it as the trigger, and you narrow the audience further with targeting rules. The result is fewer prompts, and the prompts that do fire land on happier users. The guiding principle: a store rating is expensive. Both Apple and Google limit how often the native sheet can appear, so every call is effectively a finite resource. Spend it on users who have already shown positive engagement. Never spend it on a user the moment they open the app for the first time. A common extension is to run a **sentiment check** in front of the native prompt: a custom in-app question that asks the user if they are enjoying the app. Only users who answer positively are eligible for the Rate & Review campaign. Negative responders are routed to an in-app feedback form instead of the public store listing. This keeps low-star feedback inside the product where it can be acted on, rather than on the store page where it hurts acquisition. See [custom-popups.md](/user-guide/custom-popups) for the front-end of that flow. ## Pick the positive-moment event Before touching the dashboard, decide what counts as a positive moment in your product. Good candidates: * A task the user came to the app to complete (an export, a transaction, a save). * A streak or milestone (seventh consecutive day, tenth item added). * A positive response to an in-app sentiment question. Bad candidates: * App launch / session start. * A screen view with no action. * Any event that also fires during errors or failed flows. The event must be tracked by the mobile SDK. If it isn't yet, ask engineering to add one `Amply.track(...)` call at the right spot. Name it something recognizable, for example `PositiveMoment`, `TaskCompleted`, or `PositiveRatingShared`. ## Worked example — positive-moment trigger A fitness app tracks `WorkoutCompleted` whenever a user finishes a session. The team decides any user who has completed at least three workouts in the app's history is a strong candidate for a five-star rating. * **Triggering event**: `WorkoutCompleted`. * **Repeat Rules**: on the third occurrence globally (not session-scoped). * **Frequency Limits**: one prompt per device, lifetime. * **Who**: app version is current, country is a launch market. Result: users who hit the workout milestone see the store prompt once, ever. Everyone else is invisible to the campaign. ## Create the campaign 1. Open **Campaigns** in the project sidebar and click **New campaign**. 2. Enter a name. Choose type **Rate & Review**. 3. **Who** — narrow the audience so the prompt lands on engaged users only. Typical conditions: * **App Version** — exclude users on older builds that have known bugs. * **Custom Property** (for example `subscription_status == "active"`) — only prompt users who have completed onboarding or paid. * **Install Date** — exclude brand-new installs (the store caps repeat prompts, so spending a prompt on a first-day user is risky). 4. **When** — set the **Triggering event** to the positive-moment event you picked. * Under **Repeat Rules**, set the campaign to fire only after the event has occurred enough times to be meaningful (for example, on the third `TaskCompleted`, not the first). * Under **Frequency Limits**, cap the campaign to one prompt per device across a long window. The store will not show the native sheet more often than its own policy allows, so burning attempts is wasteful. 5. **What** — Rate & Review campaigns do not need a deeplink URL. The SDK calls the native review API on both platforms. 6. Save as **Draft**, verify (see [testing-and-rollout.md](/user-guide/testing-and-rollout)), then move to **Active**. ## How delivery behaves on each platform The campaign asks the platform to show its native review sheet. The platform decides whether to actually display it. | Platform | Behavior | | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | iOS | Triggers the native iOS rate prompt (handled by the SDK). iOS throttles prompts per user per app, so not every call results in a visible sheet. | | Android | Calls the Play Store in-app review API. In Play Store-distributed release builds the sheet may appear. In debug or sideloaded builds the SDK shows a simulated dialog that does not post a review. | Because the store limits visibility, never design a flow that assumes the prompt definitely appeared. Treat it as best-effort. ## Measuring success Keep an eye on: * The count of campaign triggers in the campaign detail view. This counts matched evaluations, not confirmed native sheet displays — the store decides whether the sheet actually appears. * Your store rating over time (App Store Connect and Play Console both show weekly averages). * The share of low-star reviews. If a negative-feedback side-flow is in place, low-star store reviews should trend down. * The distribution of positive-moment event counts per user. If most users never reach the trigger, the event is too rare and the campaign will never fire for them. If every user hits it in the first session, the event is too cheap and the prompt will be wasted on people who haven't seen enough value yet. ## Variations * **Three-step flow** — custom sentiment popup, then Rate & Review for positives, in-app feedback deeplink for negatives. Most powerful; requires a custom popup and a feedback form in the app. See [custom-popups.md](/user-guide/custom-popups) for the popup side and [managing-deeplinks.md](/user-guide/managing-deeplinks) for the feedback deeplink. * **Single-event flow** — pick one strong positive event and gate directly on it. Minimal setup, good default. Start here if you don't yet have a sentiment popup built. * **Audience-only flow** — for apps without a clear positive moment, gate by `session.counter >= N` and a retention-indicating custom property. Weaker signal, still better than untargeted. ## Common pitfalls * **Prompting too early.** Firing on session 1 or session 2 burns the store's allowance on users who haven't experienced the product yet. Wait for a retention signal. * **Prompting everyone who crosses the event.** The event alone is not enough — combine it with an audience filter so churned or dormant users are excluded. * **Forgetting frequency limits.** Even a well-chosen event will fire repeatedly for power users. Cap to one prompt per long window per device. * **Testing on a debug build and assuming production works.** The Android Play Store in-app review API only works in Play-distributed release builds. A positive test on a debug build only tells you the campaign evaluated; it does not confirm a live sheet will appear. ## Maintenance Rate & Review campaigns are not set-and-forget. Review them quarterly: * Confirm the positive-moment event is still a strong signal. Products evolve; the event that correlated with happiness last year may not this year. * Check whether any low-star reviews are still citing issues that should have been caught by the audience filter (for example, users on an unsupported OS version). Tighten the audience if so. * If your app now has an in-app feedback form, upgrade the flow to the three-step variation so negatives never reach the store. ## Related * [Custom popups](/user-guide/custom-popups) — build the sentiment check that feeds this flow. * [Managing deeplinks](/user-guide/managing-deeplinks) — route low-rating users to an in-app feedback form. * [Campaign actions](/concepts/campaign-actions) — how the action types fit together. * [Campaigns](/user-guide/campaigns) — campaign structure reference. # Custom popup flows Amply doesn't have a native Custom Popup campaign type today — this page documents the shipped pattern: fire a DeepLink campaign to an in-app popup screen your app renders. A custom popup is an in-app message you control — the title, the body, the buttons, and what happens on tap. Today you create custom popups by pairing a **Deep Link** campaign with a screen your app already knows how to render. The dashboard decides when to show it and to whom; the app decides how it looks. **Use this when** you need to communicate something in your own visual language (sentiment checks, feedback prompts, in-app offers, soft push pre-prompts) at a specific moment in the user's session. **Don't use this when** you only need to route the user to an existing screen — a plain [deeplink campaign](/user-guide/managing-deeplinks) is simpler. Also don't use this for the native review sheet — use a [Rate & Review campaign](/user-guide/rate-review-flows) instead. ## Custom popup vs deeplink — quick rule * If the outcome is "take the user to an existing screen," use a deeplink campaign with no popup. * If the outcome is "show a message or ask a question inside the app," use a custom popup (delivered as a deeplink to a dedicated popup screen). * If the outcome is "show the native store review sheet," use a Rate & Review campaign. ## How it works today Your mobile team implements one reusable popup screen. That screen reads parameters from the deeplink URL — title, body, primary CTA label, secondary CTA label, variant — and renders them using your design system. You then create a Deep Link campaign whose URL points at that popup screen. Result: the dashboard controls *when* the popup shows and *what text* it shows. The app controls how it looks and what the buttons do. Content changes do not require a release. {% hint style="info" %} A native "Custom Popup" campaign type is planned. Until it ships, the deeplink-to-popup-screen pattern described below is the supported approach. {% endhint %} ## Before you start Engineering needs to have built the popup screen once. Agree on: * The URL shape. Example: `yourapp://popup?id=sentiment_check&title=Enjoying%20the%20app?&primary=Yes&secondary=Not%20really`. * Which parameters are supported (title, body, primary/secondary CTA, icon, variant). * What each CTA does. Common patterns: dismiss, track an event, fire a second deeplink, open system settings. Document the contract somewhere the marketing team can reference without reading code. The developer-side docs for this live at [Showing custom popups](/developer-guide/showing-custom-popups). ## Create a popup campaign 1. Open **Campaigns** → **New campaign**. Enter a name. Choose type **Deep Link**. 2. **Who** — define the audience. Standard targeting applies: countries, app version, install date, custom properties. 3. **When** — pick the **Triggering event** and configure repeat rules and frequency limits. Custom popups are fatiguing if overused. A one-per-device limit on a 30-day window is a safe default for non-time-critical prompts. 4. **What** — build the **DeepLink** URL that encodes the popup content. For the example sentiment check: ``` yourapp://popup?id=sentiment_check&title=Enjoying+the+app%3F&primary=Yes&secondary=Not+really ``` Parameter values must be URL-encoded. Test long strings carefully. 5. Save as **Draft**. Verify in a staging build. Promote to **Active**. ## Content fields The exact fields depend on what your app's popup screen supports. A typical contract: | Field | Purpose | Notes | | ----------- | ---------------------------------------- | ---------------------------------------------------------------- | | `id` | Unique identifier for the popup template | Lets the app apply variant-specific layout or tracking. | | `title` | Bold top line | Keep under 40 characters — it wraps awkwardly on small screens. | | `body` | Supporting sentence | Optional. Keep under 120 characters. | | `primary` | Main button label | Should match the intended action, not say "OK". | | `secondary` | Secondary button label | Optional. Use for a soft dismiss ("Not now") or a counter-offer. | | `icon` | Icon key the app recognizes | Optional. | | `variant` | Style key (info, warning, celebration) | Optional. | ## Display rules Every rule from the [Campaigns](/user-guide/campaigns) page applies. The ones that matter most for popups: * **Repeat Rules** — show after the Nth fire of the event, not the first. * **Frequency Limits** — cap per device over a time window. Popups that appear more than once a week feel broken. * **Audience filters** — exclude users who already completed the goal (for example, exclude users whose custom property `invited_friends` is true from the invite popup). ## When a popup is the wrong tool * If you need to block the user from using a feature until they act, that belongs in app-side logic, not a popup campaign. * If you need a multi-step form, deeplink into a full screen, not a popup. * If the message is time-critical and users must act within hours, a push notification is a better channel. ## Worked example — soft push pre-prompt Goal: ask users whether they want notifications inside your UI before triggering the system permission dialog. If they say no, never call the system API (the system prompt can only be shown once). * **Who**: users who have not yet been asked (custom property `push_asked` is not set). * **When**: event `OnboardingFinished`, repeat every event, one-per-device frequency limit. * **What**: `yourapp://popup?id=soft_push&title=Get+updates%3F&primary=Yes&secondary=Maybe+later`. In the app, the popup screen reads `id=soft_push`. "Yes" calls the system push API; "Maybe later" sets `push_asked=true` and closes the popup. ## Worked example — feature feedback Goal: collect a one-tap reaction after a user has interacted with a new feature twice. * **Who**: users with custom property `feature_x_uses >= 2` and `feedback_given` not set. * **When**: event `FeatureXClosed`. * **What**: `yourapp://popup?id=feature_x_feedback&title=How+was+it%3F&primary=%F0%9F%94%A5&secondary=Meh`. Tap handlers track the answer as an event and set `feedback_given=true`. ## Related * [Managing deeplinks](/user-guide/managing-deeplinks) — because popups are delivered as deeplinks. * [Campaign actions](/concepts/campaign-actions) — the concept page covering campaign action types. * [Showing custom popups](/developer-guide/showing-custom-popups) — engineer-side integration. * [Rate & Review flows](/user-guide/rate-review-flows) — combine a sentiment popup with a gated review prompt. # Sessions and events The Events screen is where you confirm the events your campaigns rely on are actually arriving — and where you turn individual events on or off for campaign use. > Dashboard task page. For the model of sessions and events, see [Sessions and events](/concepts/sessions-and-events). **Use this when** you're setting up a campaign and want to verify its triggering event is being reported, or you're auditing what the SDK knows about. **Don't use this when** you need a per-user analytics report — Amply isn't a BI tool. ## What the Events screen shows In a project, open **Events**. You'll see one row per event name, each with: * **Name** — the exact event name as reported by the SDK. * **Last Seen** — when the event was last seen on each platform. iOS and Android are listed separately, with the SDK's most recent timestamp per platform. Blank if a platform has never reported it. * **Available** — a toggle. When off, the event is hidden from campaign configuration dropdowns. The list covers every event name the SDK has ever reported for this project, across all users and devices. New names appear as soon as the first device reports them. ## Using events in a campaign The most common flow: 1. Open **Events** and find the name you want to trigger on. 2. Confirm **Last Seen** shows a recent timestamp on the platforms you care about — that's proof the event is actually arriving. 3. Go to **Campaigns** → **New campaign**, and in the **When** step, pick that event from the **Trigger when event** dropdown. 4. Optionally add parameter filters ("only when `tier` equals `premium`"). If an event isn't in the dropdown: * It might be toggled off — flip **Available** back on. * It might not have been reported yet — ask an engineer to trigger it on a test device, then refresh. * The name might be different from what you expect — copy-paste from the Events screen rather than typing. ## Turning events on and off The **Available** toggle on each row controls whether the event is offered in campaign configuration dropdowns (the Triggering Event picker and custom-property pickers elsewhere in the form). * Turn off noisy or low-signal events you don't want listed in the dropdowns. * Turn on an event you had previously disabled. Toggling **Available** does not stop the SDK from sending the event — it only affects what the dashboard offers for configuration. ## A note on custom events Custom events are event names your app sends from code. As a PM your role is usually: 1. Decide what events you need (names and properties) for a campaign. 2. Hand the list to your engineer. 3. Once they've shipped, watch the Events screen to confirm the names show up. 4. Use them in campaigns. For the standard events the SDK reports automatically, the naming conventions, and how custom events get tracked from code, see [Sessions and events](/concepts/sessions-and-events) and [Tracking events](/developer-guide/tracking-events). ## Related * [Sessions and events (concepts)](/concepts/sessions-and-events) — the model: sessions, the standard event catalog, naming conventions * [Creating a campaign](/user-guide/creating-a-campaign) — picking a triggering event in the When step * [Targeting an audience](/user-guide/targeting-an-audience) — using event-sourced properties as audience rules * [Tracking events](/developer-guide/tracking-events) — how engineers send custom events from the SDK # Testing and rollout Every campaign change goes live the moment you save it and move the campaign to **Active**. There is no app release, no review window, and no store approval. That release-free control is what Amply's orchestration is for — and it's also why you need a testing routine. This page covers how to validate a campaign in staging, how to stage the rollout yourself using audience targeting, and how to pull a campaign instantly if something is wrong. **Use this when** you are about to publish a campaign to real users, or a live campaign is misbehaving. **Don't use this when** you are still iterating on the rule design and haven't yet decided what to validate. {% hint style="info" %} Amply has no staging/QA state — the safest test is an Active campaign with an audience of one. Draft campaigns are not evaluated for live traffic. {% endhint %} ## Why "no release required" matters Changing in-app behavior normally means: code change → internal QA → store submission → store review (often days) → phased store rollout → users finally see the change. Amply skips all of that for anything you express as a campaign. * **Change a trigger**: edit the **When** step, save. Users who start a session after the change use the new rules. * **Change the audience**: edit the **Who** step, save. * **Change the deeplink URL**: edit the **What** step, save. * **Pull the campaign**: change state from **Active** to **Cancel**. New evaluations stop immediately. The app code — the deeplink handler, the popup screen, the SDK — does not change. Only the rules the dashboard evaluates change. ## Phase 1 — Validate in staging before publishing Only **Active** campaigns are evaluated. To test without exposing users, narrow the **Who** rules so the campaign matches only your test device, then move it to **Active**. Keep the narrow rules until you have verified behavior, then widen. ### Step 1: wire the staging build to the same project Your mobile team runs a staging build that points at the same Amply project used for production. If they run a separate project for staging, make the test campaign in that project instead — and remember to re-create it in production after validation. ### Step 2: make yourself match the audience The cleanest way to test: temporarily narrow the campaign to an audience that is only you. * Set a **Custom Property** condition like `qa_tester == "your-name"` and set that property from the staging app. * Or narrow by **Country**, **OS Version**, or **App Version** to a combination only your test device matches. If the campaign will eventually target everyone, keep the narrow version Active until you have verified behavior, then widen the audience. ### Step 3: fire the trigger and confirm delivery 1. Ensure the campaign is **Active** while you test (Draft campaigns are skipped). 2. Fire the **Triggering event** by doing whatever action calls `Amply.track(...)` in the app, or by restarting the app if the trigger is `SessionStarted`. 3. Watch the deeplink listener (for Deep Link campaigns) or the native review sheet (for Rate & Review). 4. If nothing happens, check the campaign detail page for the trigger count — it increments when a match is recorded, regardless of whether the action visibly succeeded. ### Step 4: widen the audience and move to production use Once behavior is correct: 1. Edit the **Who** step to the real production audience. 2. Save. The campaign is now targeting real users but still in Active state on your test device, so double-check once more. ### Troubleshooting | Symptom | Likely cause | | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | No trigger count increments | Campaign is in **Draft**, or the triggering event name has a typo (they are case-sensitive). | | Trigger count increments but nothing visible happens in the app | Deeplink handler not registered, or the URL scheme doesn't match what the app expects. | | Some users trigger but not others | Audience conditions exclude them. Check country, app version, and custom property filters. | | Campaign fires too often | **Frequency Limits** not set or set too permissively. | | Campaign does not fire again for the same user | Frequency limit was hit. Increase the window or raise the cap. | ## Phase 2 — Control who sees it (phased rollout) Amply does not ship a percentage-based rollout slider today. You get the same effect by widening the audience in steps. 1. **Start narrow.** When moving from Draft to Active, keep the **Who** targeting tight: one country, latest app version, maybe a specific custom property. 2. **Wait, then measure.** Check the campaign detail view for trigger counts and any downstream events (for example, post-popup `feedback_given`). Cross-reference with product analytics for any regression on the core KPIs. 3. **Widen.** Edit the **Who** step and remove one constraint (add more countries, drop the app-version filter). Save. 4. **Repeat** until the audience is what you want it to be. Because edits to an Active campaign take effect within minutes, each widening step lands in minutes, not days. ## Instant rollback If a live campaign is hurting users — wrong screen, broken deeplink, prompt firing too often — stop it immediately: 1. Open the campaign. 2. Change state from **Active** to **Cancel** (or use the state control on the list view). From that moment on, the campaign stops matching and no new deliveries happen. Work that was already dispatched to an in-flight session may still complete, but nothing new starts. A cancelled campaign stays in the list. You can fix the issue, then either: * Return it to **Active** (same campaign, same ID, keeps historical counts), or * Duplicate it into a new **Draft**, edit, validate, activate (use this if the fix is significant). ## Checklist before you move a campaign to Active * [ ] The campaign ran end-to-end on a staging or real test device. * [ ] The audience condition that narrowed it to you has been removed or broadened. * [ ] **Frequency Limits** are set. At least one cap per device per time window. * [ ] The deeplink URL or review-prompt behavior is what you expect. * [ ] Someone else on the team knows the campaign is going live. ## Related * [Managing deeplinks](/user-guide/managing-deeplinks) — testing deeplink campaigns specifically. * [Rate & Review flows](/user-guide/rate-review-flows) — testing native review prompts. * [Custom popups](/user-guide/custom-popups) — testing popup content. * [Testing your integration](/developer-guide/testing-your-integration) — the engineer-side checklist. # Entry-based onboarding routing Route users into different onboarding flows based on the Custom Product Page or ad creative that brought them in — no release required. **Use this when** you run multiple CPPs or ad creatives and each one promises a different first-run experience. **Don't use this when** every acquisition source leads to the same product promise; routing adds noise without payoff. ## Goal Ads sell one thing, the app opens into another. If CPP A promises "meal planning in 30 seconds" and CPP B promises "calorie tracking for athletes," the generic onboarding flow breaks the promise for both. This recipe splits onboarding by entry point so each cohort sees the flow that matches the creative they clicked. ## Setup ### In the dashboard * Create one campaign per entry point. Name them after the CPP or creative ID: `onboarding-cpp-meal-planner`, `onboarding-cpp-athlete`, `onboarding-default`. * Trigger: session start, first session only. * In the conditions editor, gate each campaign on an attribute that identifies the source (for example, `acquisition_source = "cpp_meal_planner"`). * Action: show the matching onboarding deeplink (`yourapp://onboarding/meal-planner`, etc.). * Make `onboarding-default` the fallback with the broadest audience — no source condition at all — so organic installs (with no `acquisition_source` value) match it while the narrower, source-gated campaigns match their own cohorts. * Publish all three at once so first-session users always match exactly one. ### In the app (engineering hand-off) * On install, read the entry-point hint from the attribution SDK or the CPP query string and write it as a user attribute: ```swift amply.setCustomProperty(key: "acquisition_source", value: "cpp_meal_planner") ``` * Register a deeplink handler that maps `yourapp://onboarding/` to the corresponding in-app flow controller. * Call `setCustomProperty` before the first session starts so the first campaign evaluation sees the right value. ## How it runs 1. User taps an ad, lands on CPP A, installs the app. 2. App boots, SDK initializes, attribution library resolves the source, app writes `acquisition_source = "cpp_meal_planner"`. 3. Session starts. Amply evaluates candidate campaigns. The narrower `acquisition_source` condition on `onboarding-cpp-meal-planner` matches this user; the broader `onboarding-default` would also match but is selected only when no narrower campaign does. 4. Amply fires the deeplink `yourapp://onboarding/meal-planner`. The app routes into the meal-planner flow. 5. User finishes onboarding. Subsequent sessions evaluate again — the campaign is first-session-only, so it does not fire again. 6. A user who installs organically matches no source and falls through to `onboarding-default`. ## Metrics to watch * Onboarding completion rate, split by `acquisition_source`. Expect the segmented flows to beat the generic one by 10-25%. * Trial-start rate in the first 24 hours, again split by source. * Drop-off step within each flow. If a segmented flow is worse than the default, the creative and the flow are misaligned. * Deeplink resolve success rate. A sudden drop means the app is not handling one of the new URLs. ## Related * [Creating a campaign](/user-guide/creating-a-campaign) — building the campaigns used here * [Targeting an audience](/user-guide/targeting-an-audience) — how the source condition is expressed * [Managing deeplinks](/user-guide/managing-deeplinks) — registering the onboarding routes * [User attributes](/concepts/user-attributes) — why `acquisition_source` belongs on the user, not the event * [Handling deeplinks](/developer-guide/handling-deeplinks) — the deeplink listener on the SDK side * [AI-assisted integration](/getting-started/ai-assisted-integration) — describe this campaign in plain language and have your AI assistant build it # Paywall versioning Swap paywall variants, target them to specific cohorts, and roll back the same day — no App Store or Play Store submission. **Use this when** you want to test seasonal pricing, headline copy, or a new paywall layout without blocking on a release train. **Don't use this when** the variant needs new native UI that is not already shipped in the build; remote config cannot introduce new screens, only pick between ones that exist. ## Goal Paywall changes that live in app code are expensive to iterate on: two weeks of review, a rollback means another submission, and you cannot target a variant to a specific cohort. This recipe ships the paywall as a remote-selectable deeplink so the dashboard decides which variant a given user sees and when. ## Setup ### In the dashboard * Create one campaign per variant: `paywall-control`, `paywall-winter-offer`, `paywall-long-copy`. * Trigger: session start, or on a custom event like `PaywallRequested` fired from a feature gate. * Target audience: the free cohort (`subscription_status != "pro"`). * Split variants by audience filter rather than a percentage split — for example, send `paywall-winter-offer` to users with `country` in `["US","CA"]`, `paywall-long-copy` to users with `install_date` after a given date, and leave `paywall-control` as the broadest-audience fallback that catches every free user not matched by a narrower variant. * Action: fire the deeplink for that variant (`yourapp://paywall/control`, `yourapp://paywall/winter`, `yourapp://paywall/long-copy`). * To retire a seasonal variant, move its campaign state to `Cancel` on the planned end date. The change propagates on the next session. Use `Draft` state to stage a variant that is not yet live. ### In the app (engineering hand-off) * Ship every variant screen in the build before you promote the campaign. Remote config selects between them; it cannot create them. * Register a deeplink handler for `yourapp://paywall/` that resolves `` to the matching view controller. * Track the outcome so variants are comparable: ```typescript await Amply.track({ name: 'PaywallViewed', properties: { variant: 'winter' }}); await Amply.track({ name: 'PurchaseCompleted', properties: { variant: 'winter', product: sku }}); ``` ## How it runs 1. User opens the app. Session starts. 2. Amply evaluates the paywall campaigns. The user's `country` is `"US"`, so the narrower `paywall-winter-offer` audience matches; the broader `paywall-control` audience would also match but is only selected when no narrower variant does. 3. Amply fires `yourapp://paywall/winter`. The app presents the winter variant. 4. App tracks `PaywallViewed` with `variant: "winter"`. If the user converts, `PurchaseCompleted` carries the same variant tag. 5. The growth team compares conversion across `variant` values in their analytics tool. 6. When the winter window closes, the operator moves that campaign to `Cancel`. Amply stops firing it. Users fall back to the control variant. ## Metrics to watch * View-to-purchase rate per variant. This is the headline number. * Average revenue per paying user per variant — protects against a variant that converts more people into a worse plan. * Trial-start rate per variant, if the product has a trial. * Refund and cancel rate per variant over the following 30 days. A variant that converts well but refunds high is a net loss. ## Related * [Campaigns](/user-guide/campaigns) — the campaign types used here * [Testing and rollout](/user-guide/testing-and-rollout) — using Draft state and instant rollback * [Campaign delivery](/concepts/campaign-delivery) — how session-start and event-triggered delivery differ * [Tracking events](/developer-guide/tracking-events) — tagging purchase events with the variant * [Post-trial recovery](/recipes/post-trial-recovery) — a related recipe that also swaps paywalls by context * [AI-assisted integration](/getting-started/ai-assisted-integration) — describe this campaign in plain language and have your AI assistant build it # Post-trial recovery Catch users the first time they open the app after their trial ended and show a recovery paywall instead of the default one. **Use this when** your product has a free trial and you see a measurable cohort that lapses without converting. **Don't use this when** the app has no trial, or when lapsed users should be treated identically to free users — this recipe only pays off if the recovery paywall differs from the default. ## Goal A user opens the app on day 8, the trial ended on day 7, and the default paywall appears as it always has. You have one shot to re-sell them and you are using the same creative that did not convert them on day 1. This recipe detects the trial-ended state, fires a dedicated recovery flow with a different offer, and stops bothering them once they either convert or clearly churn. ## Setup ### In the dashboard * Create a campaign `post-trial-recovery`. * Trigger: session start. * Conditions: `trial_status = "expired"` and `subscription_status = "free"` and `sessions_since_trial_end < 5`. * Action: fire `yourapp://paywall/recovery` — a paywall that leads with a discounted annual offer or a one-time coupon. * Frequency cap: one show per session, maximum three total. * Create a follow-up campaign `post-trial-recovery-final` with the same trigger but `sessions_since_trial_end >= 5` and a sharper offer. Cap it at one show, ever. * End state: when the user subscribes, set `subscription_status = "pro"`. Both campaigns stop matching. ### In the app (engineering hand-off) * When your billing library reports trial expiration, update the user attributes: ```kotlin amply.setCustomProperty("trial_status", "expired") amply.setCustomProperty("subscription_status", "free") amply.setCustomProperty("trial_ended_at", trialEndDate) ``` * Track a session counter that increments only while `trial_status = "expired"`: ```kotlin amply.setCustomProperty("sessions_since_trial_end", count) ``` * Register the `yourapp://paywall/recovery` deeplink to present the recovery screen. ## How it runs 1. User installs, starts a 7-day trial. `trial_status = "active"`. 2. Day 7: billing library fires trial-ended. App sets `trial_status = "expired"`, `subscription_status = "free"`, `sessions_since_trial_end = 0`. 3. Day 8: user opens the app. Session starts. Counter is now `1`. `post-trial-recovery` matches. Amply fires the recovery deeplink. User sees the 40%-off annual offer instead of the default paywall. 4. User dismisses. Counter becomes `2`, `3`, `4` over the next few sessions. Campaign continues to match (counter stays below 5), capped at three total shows. 5. On the session where the counter reaches 5, `post-trial-recovery` no longer matches and `post-trial-recovery-final` does. A last-chance offer appears. 6. User subscribes. App sets `subscription_status = "pro"`. Neither campaign matches from this session onward. ## Metrics to watch * Recovery paywall view-to-purchase rate. Compare against default paywall conversion for the same cohort. * Days-to-conversion after trial end. Shorter is better. * Share of trial-ended users who ever return. If this is <20%, the recovery window is wasted; move the effort to push or email. * Long-term retention of recovered subscribers versus first-session subscribers. A bad recovery offer buys expensive churn. ## Related * [Paywall versioning](/recipes/paywall-versioning) — swap the recovery paywall variant itself * [Reactivation after inactivity](/recipes/reactivation-after-inactivity) — the same pattern for users with no trial signal * [Campaigns](/user-guide/campaigns) — frequency caps and session-start triggers * [User attributes](/concepts/user-attributes) — modeling trial and subscription state * [User attributes how-to](/developer-guide/user-attributes) — writing the attributes from the app * [AI-assisted integration](/getting-started/ai-assisted-integration) — describe this campaign in plain language and have your AI assistant build it # Reactivation after inactivity Detect when a user returns after a quiet stretch and route them into a welcome-back flow instead of the normal home screen. **Use this when** you want a calendar-based signal — days since last open — and a coarse "they drifted" cutoff is good enough to act on. **Don't use this when** you have behavioral data that can detect slowdowns before the calendar gap opens; reach for [Winback at-risk users](/recipes/winback-at-risk) instead. Also skip for apps with high daily-use cadence where a 7-day gap is noise. ## Goal A user who returns after a 14-day gap is effectively a new user again — they have forgotten where things are, what the value was, and why they were paying. Dropping them on the home screen wastes the moment. This recipe fires a reactivation flow on the first session back: a short recap, a contextual offer, or a reminder of the one feature they used most. ## Setup ### In the dashboard * Create a campaign `reactivation-inactive-7d`. * Trigger: session start. * Conditions: `days_since_last_session >= 7` and `days_since_last_session < 30` and `subscription_status = "free"`. * Action: fire `yourapp://reactivation/welcome-back` with a trial extension or a feature recap. * Create a second campaign `reactivation-inactive-30d` with `days_since_last_session >= 30`. Use a stronger offer; these users are closer to uninstall. * Frequency: once per returning session. A user who comes back, leaves again, and returns a week later should see it fresh. * Exclude paying users unless you specifically want to retain lapsed payers. ### In the app (engineering hand-off) * On every session start, compute the gap from the last session timestamp and write it before Amply evaluates campaigns: ```swift amply.setCustomProperty(key: "days_since_last_session", value: gapDays) amply.setCustomProperty(key: "last_core_feature", value: lastFeatureUsed) ``` * Register `yourapp://reactivation/welcome-back` to present the recap screen. Populate it with `last_core_feature` so the screen refers to something the user actually did. * Track the outcome: ```swift amply.track("ReactivationShown") amply.track("ReactivationConverted") ``` ## How it runs 1. User installs, uses the app for a week, then stops. 2. Fourteen days later, the user opens the app. SDK starts a session. 3. App reads `last_session_at` from local storage, computes `days_since_last_session = 14`, writes it as a user attribute. 4. Amply evaluates campaigns. `reactivation-inactive-7d` matches. 5. Amply fires `yourapp://reactivation/welcome-back`. The app shows the recap screen with the user's previous favorite feature and a trial-extension button. 6. User either converts (app tracks `ReactivationConverted` and the campaign stops matching for this session) or dismisses. Either way, next time the user opens the app within a few days, the gap is small and the campaign no longer matches. ## Metrics to watch * Return-session-to-conversion rate. Compare the cohort that saw the reactivation flow to a hold-out. * 7-day retention after the reactivation session. The point of the flow is to restart the habit, not just extract one purchase. * Uninstall rate in the 72 hours after the flow. A pushy offer can accelerate churn it was meant to prevent. * Feature re-engagement: did the user actually use `last_core_feature` again in this session? ## Related * [Post-trial recovery](/recipes/post-trial-recovery) — reactivation for the trial-specific case * [Winback at-risk users](/recipes/winback-at-risk) — a finer-grained version triggered by a behavioral signal, not a calendar gap * [Sessions and events](/concepts/sessions-and-events) — how session boundaries are defined * [Targeting an audience](/user-guide/targeting-an-audience) — composing the inactivity condition * [Tracking events](/developer-guide/tracking-events) — instrumenting the reactivation outcome * [AI-assisted integration](/getting-started/ai-assisted-integration) — describe this campaign in plain language and have your AI assistant build it # Seasonal campaigns Ship a time-bound campaign — Black Friday, World Cup, app anniversary — by activating and cancelling a dashboard campaign on a planned calendar. **Use this when** the promotion has a clear start and end date and you want to avoid shipping two app releases around it. **Don't use this when** the offer is permanent; evergreen offers belong in the default paywall, not a campaign. ## Goal Seasonal promos historically mean a rushed release the week before, a second release to take the banner down, and a third if the end date slips. This recipe replaces the release cycle with a single dashboard campaign that an operator activates on the start date and cancels on the end date — no code ships between the two dates. ## Setup ### In the dashboard * Create a campaign `bf-2026-annual-50off` and keep it in `Draft` state while you prepare it. * Trigger: session start, plus a second campaign triggered on `CheckoutOpened` so the user sees the banner both passively and at intent. * Audience: free users in markets where the offer is valid (`country` in `["US", "CA", "GB", "DE"]`). * Action: fire `yourapp://paywall/black-friday` pointing to a holiday-themed paywall with the 50%-off annual SKU. * Frequency: once per session, capped at four sessions total. * On the planned start date, move the campaign to `Active`. On the end date, move it to `Cancel`. The default paywall campaign stays running throughout and reclaims every session once the seasonal campaign is cancelled. ### In the app (engineering hand-off) * Ship the seasonal paywall screen in a release before the start date. Remote scheduling cannot introduce new screens. * Ensure the correct SKU is approved in App Store Connect and Google Play well before the start date. * Register the `yourapp://paywall/black-friday` deeplink. * Set region on the user so targeting works: ```typescript await Amply.setCustomProperty('country', deviceCountry); ``` ## How it runs 1. Before November 24, the campaign sits in `Draft`. The default paywall runs normally. 2. On the morning of November 24, the operator moves the campaign to `Active`. Users in the target markets who open the app from then on see the seasonal paywall. 3. During the window, users can hit the paywall up to four times across sessions. After that, the frequency cap silences it and the default paywall returns for that user. 4. A user outside the target countries never matches. They continue to see the default paywall throughout. 5. On December 2, the operator moves the campaign to `Cancel`. The default paywall immediately reclaims every session. 6. The team reviews the campaign report in the dashboard and decides whether to re-run the same campaign with tweaks for Cyber Monday next year. ## Metrics to watch * View-to-purchase rate during the window versus the default paywall in the same window a year prior. * Share of revenue from the seasonal SKU — cannibalization matters. If monthly revenue drops as annual-50off rises, check whether you pulled forward demand. * Post-window cancel rate at day 30 and day 60. Discount-led cohorts often churn earlier. * Regional split. If one country converts dramatically worse, the creative or the localization is off. ## Related * [Paywall versioning](/recipes/paywall-versioning) — the underlying variant pattern this recipe relies on * [Testing and rollout](/user-guide/testing-and-rollout) — previewing the campaign before it goes live * [Creating a campaign](/user-guide/creating-a-campaign) — moving a campaign through Draft → Active → Cancel * [Targeting an audience](/user-guide/targeting-an-audience) — country and segment filters * [Campaign delivery](/concepts/campaign-delivery) — how overlapping campaigns are evaluated * [AI-assisted integration](/getting-started/ai-assisted-integration) — describe this campaign in plain language and have your AI assistant build it # Rate review at a positive moment Show the native rate-review prompt only to users who have just signaled satisfaction — not to everyone on session 3. **Use this when** your store rating is dragged down by users asked at the wrong moment. **Don't use this when** you have no reliable "positive moment" event. Firing at a random session is no better than the stock prompt. ## Goal The stock "rate us" prompt on session 3 pulls from the whole population, including frustrated users. Those users rate 1 and 2 stars. This recipe gates the native prompt behind a light custom popup that first asks "how's it going?" — and only triggers the store rating if the user says it is going well. The effect is a higher average store rating because you never invite the unhappy cohort to the store at all. ## Setup ### In the dashboard * Create a campaign `rating-prompt-positive-moment`. * Trigger: event `PositiveSignal` (a value moment you define — streak completed, goal hit, purchase confirmed). * Conditions: `subscription_status != "new"` (avoid brand-new users), `store_rating_shown != true`, session count `>= 3`. * Action: fire a deeplink to your in-app sentiment popup, e.g. `yourapp://popup/sentiment-check`. The popup asks "Enjoying the app?" with two buttons: "Yes" / "Not really". See [Custom popups](/user-guide/custom-popups) for how the popup-as-deeplink pattern works today. * Branch on the popup result (handled in-app, not in the dashboard): * "Yes" → the app calls the native rate-review prompt. * "Not really" → the app opens `yourapp://feedback/form` (see [Feedback capture on negative rating](/recipes/feedback-capture-on-negative-rating)). * Frequency: once per user, ever — enforced by the `store_rating_shown != true` condition in the audience, not a native frequency cap. ### In the app (engineering hand-off) Note: `session_count` is not a built-in targeting attribute — the app must increment and set it as a custom property on each session start, e.g. `amply.setCustomProperty("session_count", n)`. * Pick the single strongest "positive moment" in your product. Track it as one event, not many: ```swift amply.track("PositiveSignal", properties: ["source": "streak_7d"]) ``` * Register a popup action that calls `SKStoreReviewController.requestReview()` on iOS or `ReviewManager` on Android when Amply asks. * After the native prompt runs, mark the user: ```swift amply.setCustomProperty(key: "store_rating_shown", value: true) ``` ## How it runs 1. User completes a 7-day streak. App fires `PositiveSignal`. 2. Amply evaluates event-triggered campaigns. The user has session count `5`, has never been asked, is not a new user. `rating-prompt-positive-moment` matches. 3. Custom popup appears: "Enjoying the app?" 4. User taps "Yes". Amply triggers the native rate-review prompt. The OS shows its store rating sheet. 5. User leaves a 5-star review. App sets `store_rating_shown = true`. The campaign never matches this user again. 6. Parallel path: if the user had tapped "Not really", the feedback deeplink fires and the native prompt is never called — the unhappy user never reaches the store. ## Metrics to watch * Store rating distribution before and after rollout. Expect the 4-5 star share to rise and the 1-2 star share to fall. * Popup "Yes" share. If it is <50%, the `PositiveSignal` event is triggering too broadly. * Native prompt acceptance rate among those who said "Yes". This is the lift over the stock flow. * Written review volume. You may see fewer total reviews but a higher average — that is the desired outcome. ## Related * [Feedback capture on negative rating](/recipes/feedback-capture-on-negative-rating) — the "Not really" branch * [Rate-review flows](/user-guide/rate-review-flows) — dashboard configuration for the native prompt * [Custom popups](/user-guide/custom-popups) — building the "Enjoying the app?" popup * [Tracking events](/developer-guide/tracking-events) — defining the `PositiveSignal` event * [Sessions and events](/concepts/sessions-and-events) — when event-triggered campaigns evaluate * [AI-assisted integration](/getting-started/ai-assisted-integration) — describe this campaign in plain language and have your AI assistant build it # Feedback capture on negative rating Keep 1- and 2-star reviews out of the App Store by catching them inside the app and routing the user to a feedback form instead. **Use this when** you run the rate-review positive-moment flow and want to do something useful with the unhappy branch. **Don't use this when** you do not have an internal channel to read and answer the feedback; silent intake makes the user angrier. ## Goal If you only ask happy users to rate you, you never hear from the unhappy ones — and they eventually leave 1-star reviews anyway, just with less data for you. This recipe catches the "not really" branch of the rating popup, opens a short in-app form, captures the complaint with a reason category, and closes the loop with a confirmation. The public rating is protected and you now have actionable signal. ## Setup ### In the dashboard * This recipe is the negative branch of [rate-review-positive-moment](/recipes/rate-review-positive-moment). It reuses that recipe's sentiment popup. * When the user taps "Not really" in the popup, the app opens `yourapp://feedback/form`. No additional campaign is needed for this step — the app handles the branch locally. * Create a follow-up campaign `feedback-thanks` triggered by the event `FeedbackSubmitted`. * Action: fire deeplink `yourapp://popup/feedback-thanks` — the app renders a "Thanks — we'll get back to you" popup with a single OK button (see [Custom popups](/user-guide/custom-popups)). * Frequency: once per submission. * Do not fire the native store prompt on this branch under any circumstance. ### In the app (engineering hand-off) * Register the `yourapp://feedback/form` deeplink to open an in-app form with a reason selector (bug, missing feature, price, other) and a free-text field. * On submit, send the payload to your support inbox or help-desk and fire: ```typescript await Amply.track({ name: 'FeedbackSubmitted', properties: { reason: selectedReason, rating_bucket: 'low' } }); ``` * Suppress the native rate-review call on this branch. The positive-moment recipe's branching already does that. ## How it runs 1. User hits a positive moment. The rating popup appears: "Enjoying the app?" 2. User taps "Not really". 3. The app opens `yourapp://feedback/form` locally — no campaign is involved in this step. The in-app form opens. The user picks "missing feature" and types one sentence. 4. App sends the payload to the support inbox. App fires `FeedbackSubmitted` with the reason. 5. `feedback-thanks` matches. The confirmation popup appears. 6. Support triages the feedback. If it is a bug the team can fix, the user is followed up through the same channel. The native store prompt was never called. The App Store rating stays intact. ## Metrics to watch * Share of `PositiveSignal` firings that end in the negative branch. Rising share means something in the product got worse — this is now your canary. * Feedback submission rate once the form opens. <30% means the form is too long or the moment is wrong. * Reason-code distribution. This is the cheapest user-research feed in the product. * 1- and 2-star review count in the public stores week-over-week. ## Related * [Rate-review at a positive moment](/recipes/rate-review-positive-moment) — the other half of this flow * [Custom popups](/user-guide/custom-popups) — building the confirmation popup * [Managing deeplinks](/user-guide/managing-deeplinks) — registering the feedback form route * [Tracking events](/developer-guide/tracking-events) — firing `FeedbackSubmitted` with the reason property * [Handling deeplinks](/developer-guide/handling-deeplinks) — opening the form from the deeplink listener * [AI-assisted integration](/getting-started/ai-assisted-integration) — describe this campaign in plain language and have your AI assistant build it # Second-chance paywall Catch users on their second or third session with a limited-time discount before they uninstall — the mobile equivalent of cart abandonment. **Use this when** first-session paywall conversion is your main funnel and dismissal is your biggest leak. **Don't use this when** your paywall is shown deep in the app and most users do not see one on session 1; the "second chance" framing does not apply. ## Goal A user sees your paywall on session 1, dismisses it, and leaves. The chance that they go open the iOS or Play settings, find your subscription, and sign up on their own is effectively zero. This recipe detects the returning free user on session 2 or 3 and shows a time-limited offer at app start — a 50%-off first month, or a one-time coupon. You are catching the user before uninstall and giving them a reason to reconsider. ## Setup ### In the dashboard * Create a campaign `second-chance-paywall`. * Trigger: session start. * Conditions: `subscription_status = "free"` and `session_count` in `[2, 3]` and `paywall_dismissed_count >= 1`. * Action: fire `yourapp://paywall/second-chance` — a dedicated screen with a countdown timer and the 50%-off product. * Frequency: once per session, up to two total shows across sessions 2 and 3. * After session 3, the user no longer matches. Do not keep hammering them — that is how you earn uninstalls. ### In the app (engineering hand-off) Note: `session_count` is not a built-in targeting attribute — the app must increment and set it as a custom property on each session start, e.g. `amply.setCustomProperty("session_count", n)`. * Track dismissals so the targeting condition works: ```swift amply.track("PaywallDismissed", properties: ["variant": "default"]) amply.setCustomProperty(key: "paywall_dismissed_count", value: dismissedCount) ``` * Register `yourapp://paywall/second-chance` to the offer screen. The screen owns its countdown locally; the campaign only decides when to open it. * Ensure the 50%-off SKU is approved and fetched on launch. A paywall with a broken price tag destroys trust immediately. ## How it runs 1. Session 1: user opens the app, sees the default paywall, dismisses it. App fires `PaywallDismissed` and increments `paywall_dismissed_count` to 1. 2. User closes the app. Does not uninstall, yet. 3. Session 2, next day: app opens. Session starts. Conditions match — free, session 2, dismissed once. `second-chance-paywall` matches. 4. Amply fires `yourapp://paywall/second-chance`. The discounted offer appears before the home screen loads. 5. User either converts (app sets `subscription_status = "pro"`, campaign stops matching) or dismisses again. 6. Session 3: last chance to match. After that, the campaign is silent. The user either returns organically, churns, or hits a different campaign later. ## Metrics to watch * Conversion on session 2 and session 3 compared to a hold-out group that only sees the default paywall. * Uninstall rate in the 48 hours after session 2. A pushy second-chance paywall can accelerate the churn it is trying to prevent. * Revenue per returning session versus the baseline. * Downstream retention of second-chance converters at day 30 and 60. Discount-led subscribers usually retain worse; budget for it. ## Related * [Paywall versioning](/recipes/paywall-versioning) — shipping and testing the second-chance screen itself * [Post-trial recovery](/recipes/post-trial-recovery) — the trial-specific cousin of this recipe * [Feature-wall contextual paywall](/recipes/feature-wall-contextual-paywall) — a complementary pattern triggered on feature intent, not session count * [User attributes](/concepts/user-attributes) — modeling dismissal counts on the user * [Creating a campaign](/user-guide/creating-a-campaign) — building the session-count condition * [AI-assisted integration](/getting-started/ai-assisted-integration) — describe this campaign in plain language and have your AI assistant build it # Soft push permission Ask for push permission inside a custom popup first, so users who would decline never see the OS prompt. **Use this when** push is core to your retention strategy and the stock "allow notifications" rate is under 50%. **Don't use this when** you do not have a clear value story for push. Pre-asking for nothing-in-particular is worse than the default flow. ## Goal The OS push prompt can only be shown once. If the user taps "Don't Allow," they are effectively unreachable forever — pushing them into app settings to flip it back is not a retention strategy. This recipe shows your own popup first, with copy that explains what the user gets. Only users who tap "Yes, notify me" trigger the real OS prompt. The ones who would have tapped "Don't Allow" are silently queued for a better moment. ## Setup ### In the dashboard * Create a campaign `push-softask`. * Trigger: event `ValueMomentReached` — not session start, and not right after install. Wait until the user has seen something worth pushing about. * Conditions: `push_permission_status = "unknown"` (never asked yet). * Action: fire a deeplink to your in-app soft-ask popup, e.g. `yourapp://popup/push-softask`. The popup presents a clear value prop ("Get daily streak reminders?") and two buttons: "Yes, notify me" / "Not now". See [Custom popups](/user-guide/custom-popups) for the popup-as-deeplink pattern. * The app handles branching locally: * "Yes, notify me" → the app tracks `PushSoftAskApproved` and calls the OS prompt. * "Not now" → the app tracks `PushSoftAskDeclined`. The OS prompt is not called. * Frequency: once per user until declined, then one retry 14 days later if value has been delivered since (use a `push_softask_declined_at` attribute in the audience filter). ### In the app (engineering hand-off) Note: `session_count` is not a built-in targeting attribute — if you gate the campaign on session count (for instance, to wait past a new-user window), the app must increment and set it as a custom property on each session start, e.g. `amply.setCustomProperty("session_count", n)`. * Listen for the approved event and call the OS prompt only then: ```swift // on PushSoftAskApproved UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .badge, .sound]) { granted, _ in amply.setCustomProperty(key: "push_permission_status", value: granted ? "granted" : "denied") } ``` * On "Not now," keep `push_permission_status = "unknown"` (the OS prompt is preserved for later) and record the decline time so the 14-day retry window can be computed: `amply.setCustomProperty("push_softask_declined_at", now)`. * Track the soft-ask outcome for analysis: ```swift amply.track("PushSoftAskShown") amply.track("PushSoftAskApproved") amply.track("PushSoftAskDeclined") ``` ## How it runs 1. User installs the app. No push prompt fires. `push_permission_status = "unknown"`. 2. User uses the app and hits a meaningful moment. App tracks `ValueMomentReached`. 3. Amply evaluates event-triggered campaigns. `push-softask` matches. 4. Custom popup appears: "Get daily streak reminders?" with two buttons. 5. User taps "Yes, notify me." App fires `PushSoftAskApproved`. The OS prompt appears. User taps "Allow." `push_permission_status = "granted"`. 6. Parallel path: user taps "Not now." App fires `PushSoftAskDeclined`. The OS prompt never runs. Two weeks later, after another value moment, the campaign can re-match once with a different copy line. ## Metrics to watch * Net push opt-in rate — soft-ask approved AND OS granted — compared to the rate you get by calling the OS prompt directly. * Soft-ask show rate per user. If the popup fires too close to install, the whole gain vanishes. * Decline-then-accept rate on the 14-day retry. If this is non-zero, the retry is worth keeping. * Push-driven session count after rollout. The reason you do this is downstream sessions, not the permission number itself. ## Related * [Custom popups](/user-guide/custom-popups) — building the soft-ask popup * [Campaigns](/user-guide/campaigns) — event-triggered campaigns * [Tracking events](/developer-guide/tracking-events) — firing the soft-ask events * [User attributes](/concepts/user-attributes) — storing permission state as a user attribute * [Campaign delivery](/concepts/campaign-delivery) — frequency caps and retry windows * [AI-assisted integration](/getting-started/ai-assisted-integration) — describe this campaign in plain language and have your AI assistant build it # Feature-wall contextual paywall Show a paywall tailored to the specific Pro feature the user just tried to use, instead of a generic one. **Use this when** your product has several distinct Pro features and users try different ones; a single headline paywall underserves all of them. **Don't use this when** there is only one Pro feature worth selling; the generic paywall already talks about it. ## Goal A generic "Upgrade to Pro" paywall has to speak to everyone, so it speaks to nobody. The user who just tapped "Export to PDF" is not shopping for the abstract idea of premium — they want to export a PDF right now. This recipe intercepts the feature tap, fires a paywall whose hero section is about that exact feature, and preserves the user's intent to complete the export on conversion. ## Setup The recommended primary shape is a **single campaign** that handles every gated feature and lets the app pick the matching paywall screen locally. It keeps the dashboard small even when you ship more Pro features. (See [Variants](#variants) for a per-feature alternative.) ### In the dashboard * Create one campaign `feature-wall`. * Trigger: event `FeatureGateTriggered`. No property filter on `feature` — you will branch in the app. * Conditions: `subscription_status = "free"`. * Action: fire `yourapp://paywall/feature-wall?feature={{feature}}`. The app reads the `feature` query parameter and chooses the right paywall screen. * Frequency: unlimited — the user keeps hitting features; keep offering the relevant paywall. * On conversion, resume the blocked action (see engineering hand-off). ### In the app (engineering hand-off) * On a Pro feature tap, track the gate event with a `feature` property instead of showing a generic paywall: ```typescript await Amply.track({ name: 'FeatureGateTriggered', properties: { feature: 'pdf_export', source_screen: 'report_detail' } }); ``` * Register a single deeplink handler for `yourapp://paywall/feature-wall`. Read the `feature` query parameter and route to the matching paywall screen locally. * Ship each contextual paywall screen in the build before the campaign goes live. The deeplink cannot introduce new screens. * When the user converts, resume the feature action the user originally tapped. Do not dump them back on the home screen. ## How it runs 1. Free user taps "Export to PDF" on a report screen. 2. App fires `FeatureGateTriggered { feature: "pdf_export", source_screen: "report_detail" }`. 3. Amply evaluates event-triggered campaigns. `feature-wall` matches. 4. Amply fires `yourapp://paywall/feature-wall?feature=pdf_export`. The app reads `feature=pdf_export` and opens the PDF-export paywall screen with its own hero and preview. 5. User taps subscribe, completes purchase, `subscription_status` becomes `"pro"`. 6. App returns the user to the report screen and completes the export automatically. 7. A different free user taps "Offline mode." Same flow — `feature-wall` matches again, the deeplink carries `feature=offline_mode`, and the app opens the offline-mode paywall screen instead. ## Variants If you need to target or schedule paywalls per feature independently — for example, running a limited-time discount only on the export-to-PDF paywall — use one campaign per feature: * `feature-wall-pdf-export`, `feature-wall-offline-mode`, `feature-wall-custom-themes`. * Each campaign triggers on `FeatureGateTriggered` with a `feature = "pdf_export"` property filter and fires its own deeplink (`yourapp://paywall/pdf-export`, etc.). * Each contextual paywall can be activated, cancelled, or re-audienced independently. This scales poorly as the Pro feature set grows — prefer the single-campaign variant unless you need per-feature control. ## Metrics to watch * Conversion rate per feature gate. Compare to the generic paywall baseline — expect significant lift on the features users actually reach for. * Gate-to-convert time. Contextual paywalls usually convert faster because the intent is already there. * Top-converting features. This data tells you which Pro features to invest more in. * Post-purchase action completion. If most converters never actually export a PDF after subscribing, the intent-preservation path is broken. ## Related * [Paywall versioning](/recipes/paywall-versioning) — shipping and testing each contextual paywall * [Second-chance paywall](/recipes/second-chance-paywall) — complementary, triggered by session count instead of feature intent * [Campaigns](/user-guide/campaigns) — configuring event-triggered campaigns * [Tracking events](/developer-guide/tracking-events) — the `FeatureGateTriggered` pattern * [Handling deeplinks](/developer-guide/handling-deeplinks) — resuming the gated action after conversion * [AI-assisted integration](/getting-started/ai-assisted-integration) — describe this campaign in plain language and have your AI assistant build it # Feature feedback capture Ask a targeted feedback question after a user has used a new feature twice — while the memory is fresh and the sample is qualified. **Use this when** you have shipped a new feature and need real signal on whether it is landing before committing to more work on it. **Don't use this when** the feature has not shipped to enough users yet; the popup firing is cheap, but drawing conclusions from ten answers is not. ## Goal You ship a new section. Support is quiet, analytics shows some usage, and you have no idea whether users love it, find it confusing, or cannot find what they were looking for. Running a user-research round takes two weeks. This recipe drops a three-button popup on users who have engaged with the feature enough to have an opinion, captures the answer, and ships it to your analytics tool. You get a coarse but honest read in 48 hours. ## Setup ### In the dashboard * Create a campaign `new-section-feedback`. * Trigger: event `NewSectionUsed` with `usage_count = 2`. * Conditions: `new_section_feedback_given != true`. * Action: fire a deeplink to your in-app feedback popup, e.g. `yourapp://popup/new-section-feedback`. The popup asks "How's the new section?" with three buttons: "Love it", "Confusing", "Couldn't find what I wanted". See [Custom popups](/user-guide/custom-popups) for the popup-as-deeplink pattern. * Each button tap is handled in-app: the app tracks the answer event and dismisses the popup. No further navigation. * Frequency: once per user, ever — enforced by the `new_section_feedback_given != true` condition in the audience, not a native frequency cap. ### In the app (engineering hand-off) * Increment a usage counter and fire an event each time the feature is used: ```kotlin val count = currentCount + 1 amply.setCustomProperty("new_section_usage_count", count) amply.track("NewSectionUsed", mapOf("usage_count" to count)) ``` * On each popup button tap, track the answer and mark the user as answered: ```kotlin amply.track("NewSectionFeedback", mapOf("answer" to "love_it")) amply.setCustomProperty("new_section_feedback_given", true) ``` * Forward `NewSectionFeedback` to your analytics tool. That is where the team will read the split. ## How it runs 1. User opens the new section for the first time. App increments the counter and fires `NewSectionUsed { usage_count: 1 }`. No campaign matches — the event trigger requires `usage_count = 2`. 2. Later that day, user opens the new section again. `usage_count = 2`. `new-section-feedback` matches. 3. Custom popup appears: "How's the new section?" 4. User taps "Confusing." App fires `NewSectionFeedback { answer: "confusing" }` and sets `new_section_feedback_given = true`. 5. The popup closes. The user continues using the app. 6. Over the next week, several hundred users answer. The product team reads the "Confusing" share in analytics and opens a ticket on whichever screen ranks worst for that cohort. ## Metrics to watch * Response-rate of the popup. A healthy range is 40-70%. Under that and the moment is wrong or the copy is off. * Answer distribution. The absolute numbers matter less than the shape: "Couldn't find what I wanted" high means the information architecture is off. * Correlation with retention. Do "Love it" responders have higher 30-day retention than "Confusing" responders? That is the test of whether the feedback is predictive. * Time to first answer after feature launch. Fast feedback is the point of this recipe. ## Related * [Custom popups](/user-guide/custom-popups) — building the three-button popup * [Campaigns](/user-guide/campaigns) — event-triggered campaigns with usage-count conditions * [Tracking events](/developer-guide/tracking-events) — firing `NewSectionUsed` and `NewSectionFeedback` * [User attributes](/concepts/user-attributes) — marking `new_section_feedback_given` to prevent re-asking * [Feedback capture on negative rating](/recipes/feedback-capture-on-negative-rating) — the rating-driven cousin of this recipe * [AI-assisted integration](/getting-started/ai-assisted-integration) — describe this campaign in plain language and have your AI assistant build it # Winback for at-risk users Catch users whose behavior pattern is decaying — before they fully churn — and route them to a winback screen on their next session. **Use this when** you have behavioral data — session frequency, feature usage, cohort baselines — that can flag "slowing down" before a calendar gap opens. **Don't use this when** you only have calendar signal (last-open timestamp); reach for [Reactivation after inactivity](/recipes/reactivation-after-inactivity) instead. Also skip if the product is used every few days under normal conditions — the baseline is too shallow to drift against. ## Goal Churn prediction that waits for 30 days of inactivity is too late — by the time you act, the user has the app in an uninstall folder. This recipe fires on the next session after a behavioral drop (for example, weekly sessions fell from 5 to 1) and shows a winback surface: a value-recap screen, a small incentive, or a shortcut to the feature the user used to love. You are intervening while the user still has the app on their home screen. ## Setup ### In the dashboard * Create a campaign `winback-at-risk`. * Trigger: session start. * Conditions: `risk_status = "at_risk"` and `subscription_status != "pro_new"` (do not hassle users who just paid). * Action: fire `yourapp://winback/welcome-back` — a short screen that references the user's previous favorite feature and offers a small incentive if appropriate. * Frequency: once per transition into `at_risk`. When the user re-engages and `risk_status` flips back to `healthy`, the campaign can match again if they slip later. * Exclude users whose `last_session_at` is more than 30 days old — those need a different flow in a different channel. ### In the app (engineering hand-off) * Compute the risk signal in the app or an upstream service. Keep the definition simple and stable: ```typescript // Pseudocode: compare last 7 days to prior 28-day baseline const status = recentRate < baseline * 0.3 ? 'at_risk' : 'healthy'; await Amply.setCustomProperty('risk_status', status); await Amply.setCustomProperty('last_core_feature', lastFeature); ``` * Write `risk_status` before the session starts, so the first campaign evaluation sees the current value. * Track the outcome for measurement: ```typescript await Amply.track({ name: 'WinbackShown' }); await Amply.track({ name: 'WinbackConverted' }); ``` ## How it runs 1. User used the app \~5 times per week for a month, then dropped to \~1 per week. 2. On the first session after the drop, the app recomputes the risk signal: `risk_status = "at_risk"`. 3. Session starts. Amply evaluates campaigns. `winback-at-risk` matches. 4. Amply fires `yourapp://winback/welcome-back`. The screen shows "Your weekly streak is still here — one tap to pick up where you left off," referring to the user's last core feature. The app tracks `WinbackShown`. 5. User taps through, uses the feature again. Over the next week, usage recovers. The app recomputes `risk_status = "healthy"`. 6. If usage drops again months later, the campaign can match again. If the user goes dark for 30+ days, they fall out of this campaign's audience and belong to reactivation or email instead. ## Metrics to watch * Winback conversion rate: share of `WinbackShown` users who come back to healthy within 14 days. Compare to a hold-out that never saw the screen. * False-positive rate of the at-risk signal: users flagged at-risk who would have recovered anyway. A noisy signal burns the surface. * Long-term retention of winback-recovered users — 60 and 90 days out. A superficial recovery does not count. * Share of your free-to-paid users who ever hit at-risk. Rising share is a product-quality signal, not a campaign problem. ## Related * [Reactivation after inactivity](/recipes/reactivation-after-inactivity) — the coarser calendar-based version, used when you have no behavioral signal * [Post-trial recovery](/recipes/post-trial-recovery) — for trial users specifically * [Targeting an audience](/user-guide/targeting-an-audience) — expressing `risk_status` conditions * [User attributes](/concepts/user-attributes) — why risk status belongs on the user * [Tracking events](/developer-guide/tracking-events) — winback event instrumentation * [AI-assisted integration](/getting-started/ai-assisted-integration) — describe this campaign in plain language and have your AI assistant build it # Referral at a positive moment Fire the invite-a-friend screen at the exact moment the user just had a good experience — not from a static menu that nobody opens. **Use this when** you run a referral program whose K-factor is low because the invite CTA is buried in settings. **Don't use this when** you have no working referral program to route users into. Surfacing a broken flow is worse than hiding it. ## Goal Users recommend apps when they feel good about them, and that feeling decays within minutes. A Settings > Invite Friends link captures almost nobody because it requires intent; the invite screen has to come to the user. This recipe fires the invite surface on a tracked positive moment — a milestone, a big win, a streak — and only shows it once, because the second ask after a good moment is worse than no ask at all. ## Setup ### In the dashboard * Create a campaign `referral-positive-moment`. * Trigger: event `PositiveMoment` with property `kind` in a defined allowlist ("streak\_7d", "big\_win", "first\_export", etc.). * Conditions: `session_count >= 5`, `has_referred != true`, `subscription_status != "new"`. * Action: fire `yourapp://invite-friends`, a dedicated invite screen pre-populated with a share message and code. * Frequency: the `has_referred != true` audience condition suppresses the campaign permanently once the user shares. A user who *dismisses* without sharing keeps `has_referred = false` and may be re-asked at a later positive moment — add a native frequency cap (for example, once per 30 days) if you want to bound that. ### In the app (engineering hand-off) Note: `session_count` is not a built-in targeting attribute — the app must increment and set it as a custom property on each session start, e.g. `amply.setCustomProperty("session_count", n)`. * Pick the small list of real positive moments in your product. Fire them as one event with a `kind` property: ```swift amply.track("PositiveMoment", properties: ["kind": "streak_7d"]) ``` * Register `yourapp://invite-friends` to an invite screen that uses the platform share sheet. * On successful share, mark the user and track the outcome: ```swift amply.setCustomProperty(key: "has_referred", value: true) amply.track("ReferralShared", properties: ["kind": "streak_7d"]) ``` ## How it runs 1. User hits a 7-day streak. App fires `PositiveMoment { kind: "streak_7d" }`. 2. Amply evaluates event-triggered campaigns. User has session count 12, has not referred anyone, is past the new-user window. `referral-positive-moment` matches. 3. Amply fires `yourapp://invite-friends`. The invite sheet opens over the streak celebration screen. The copy is short and references the streak. 4. User taps "Share" and picks a messaging app. App fires `ReferralShared { kind: "streak_7d" }`. App sets `has_referred = true`. 5. Next positive moment weeks later: the same campaign evaluates, sees `has_referred = true`, and does not match. The user is not asked again. 6. Parallel path: user dismisses without sharing. `has_referred` stays `false`. The campaign could match on the next positive moment of a different `kind` if you choose to allow that — or stay one-shot if you prefer. ## Metrics to watch * Invite open rate per `kind`. Some positive moments generate far more shares than others; double down on those. * Accept rate of sent invites. The upstream CTA cannot fix a broken referral program downstream. * K-factor before and after rollout. If it does not move, the moment-timing is fine but the incentive is wrong. * Share of converted referrals who stick past 30 days. Referred users retain better than paid users when the program works. ## Related * [Rate-review at a positive moment](/recipes/rate-review-positive-moment) — the same pattern for store ratings * [Custom popups](/user-guide/custom-popups) — for a lighter popup variant before the full invite screen * [Creating a campaign](/user-guide/creating-a-campaign) — building the event-triggered campaign * [Tracking events](/developer-guide/tracking-events) — firing `PositiveMoment` consistently * [Campaign delivery](/concepts/campaign-delivery) — once-per-user frequency caps * [AI-assisted integration](/getting-started/ai-assisted-integration) — describe this campaign in plain language and have your AI assistant build it # Price management Plan, preview, and submit price changes for your in-app subscriptions and one-time products across every country your app sells in, from the dashboard. **Use this when** you want to change what users pay in one or many territories — a new base price plus an index, or a single ± percentage applied to current prices. **Don't use this when** you want to change a single product's price in a single country — do that directly in App Store Connect or Google Play Console. ## Prerequisites * The application is connected to App Store Connect or Google Play Console, and its products and current prices are visible in Amply. * Your plan includes Price Management. If you don't see the **Price Management** entry in the left nav, check your plan under [Billing](/user-guide/dashboard-tour#upgrade-the-plan). * For Android subscriptions, products must have a single base plan — multi-base-plan subscriptions aren't supported yet. ## Find it in the dashboard From the project sidebar, open **Price Management**. The landing page is **History** — every price change for the active application, drafts included. The page auto-refreshes every ten seconds while any batch is still in progress. Two buttons at the top right of History: * **New Price Change** — open the three-step form to create a draft. * **Compare** — inspect current prices across up to three products side by side. A third entry sits in the left nav under Price Management: * **Price Indexes** — manage reusable pricing matrices. ## Pricing method, in one sentence Two methods are available when you create a change: * **Base price** — set one price in one country, multiply by a price index for every other country. Best for a structured update. * **Percentage** — apply a single ± percentage to every current store price. Fastest for a uniform bump or cut. If you're not sure which to pick, open **Compare** first to inspect current prices side by side. See [Comparing prices](/price-management/comparing-prices). For the full wizard, draft workflow, and recovery actions, see [Creating a price change](/price-management/creating-a-price-change). ## Status reference A **price change** (a *batch* in the UI) goes through these states: | Status | What it means | | ---------- | -------------------------------------------------------------- | | Draft | Saved but not submitted. Edit or delete at any time. | | Pending | Submitted; queued for send. | | Sending | Actively pushing territory-by-territory updates. | | Completed | Every territory synced successfully. | | Incomplete | Some territories synced, others failed or were deferred. | | Failed | Every territory failed. | | Cancelled | You cancelled it while in flight, or it aged out. | | Deferred | Some territories are waiting on the store's rate-limit window. | **Completed**, **Incomplete**, **Failed**, and **Cancelled** are *terminal* — no more automatic retries. You can still act manually: retry failed entries, resume deferred ones, or derive a custom index from the matrix. Each territory inside a batch carries its own status: Pending, Sending, Completed, Failed, Skipped, Deferred, Cancelled, or Unchanged. **Unchanged** means the calculated new price matched the current store price — no write was needed. ## Store-specific behavior **App Store (iOS)** * Earliest start date is tomorrow — Apple rejects same-day changes. * Base price must match an **Apple price point** (a tier price Apple accepts). The form's autocomplete restricts you to valid points for the selected base country. * For subscriptions, you also choose an **audience**: "New subscribers only" (existing subscribers keep their current price) or "All subscribers." Price decreases apply to everyone regardless of the audience setting. **Google Play (Android)** * The change is accepted immediately, but can take several hours to propagate to the listing. * Subscriptions must have a single base plan. ## Who can use it Price Management is a dashboard-only feature — no SDK integration involved. The creator of every batch is recorded and shown in the **Created By** column of the history table. ## Related * [Creating a price change](/price-management/creating-a-price-change) — full walk-through of the wizard, draft workflow, and recovery actions * [Price indexes](/price-management/price-indexes) — system and custom indexes, and the CSV flow * [Comparing prices](/price-management/comparing-prices) — inspect current prices side by side * [Dashboard tour](/user-guide/dashboard-tour) — how to find Price Management and upgrade your plan if it's missing # Store credentials Create the App Store Connect and Google Play credentials Amply needs to read and update your prices — with the least-privilege access level for each store. Amply manages your App Store and Google Play prices for you — it reads your current prices and submits scheduled price changes. To do that, it needs API credentials from each store, with permission to manage pricing. You create these once per app and can revoke them at any time in the store's console. This page covers both platforms — jump to [App Store Connect (iOS)](#app-store-connect-ios) or [Google Play (Android)](#google-play-android). {% hint style="info" %} Your credentials are stored encrypted and are used only to read and update your store pricing. Grant the least-privileged role that still allows pricing — you don't need account-owner access. {% endhint %} ## At a glance | | App Store Connect (iOS) | Google Play (Android) | | ------------------------- | ------------------------------------- | --------------------------------------------- | | What you create | An App Store Connect **API key** | A Google Cloud **service account** + JSON key | | What you paste into Amply | Key ID, Issuer ID, and the `.p8` file | The service-account JSON | | Access level it needs | **App Manager** role (or higher) | **Manage store presence** + read access | | Where | App Store Connect → Users and Access | Google Cloud + Play Console | ## App Store Connect (iOS) You'll create an **App Store Connect API key** and give Amply three things: a **Key ID**, an **Issuer ID**, and a **`.p8`** private-key file. ### Before you start * Your app already exists in App Store Connect, under the team you'll create the key in (not a personal Apple ID). * Your Apple agreements, tax, and banking details are complete — otherwise price changes can fail even with valid credentials. * You can sign in to App Store Connect as an **Account Holder** or **Admin** — only these roles can create a team API key. ### Access level The key's role must be able to manage pricing. Assign it the **App Manager** role: App Manager can manage all aspects of an app, including pricing — everything Amply needs and nothing more. **Admin** also works but grants more than necessary. The **Finance** role is **not** enough — it's read-only for pricing. ### Steps 1. In App Store Connect, go to **Users and Access → Integrations → App Store Connect API**. 2. Under **Team Keys**, select **Generate API Key** (or **+**). 3. Name it (for example, "Amply price management") and set **Access** to **App Manager**, then generate. 4. Copy the **Issuer ID** (shown above the list of keys) and the new key's **Key ID**. 5. **Download the API key (`.p8`) now** — Apple lets you download it only once. 6. In Amply, open your application's **Integrations** tab and enter the **Key ID**, **Issuer ID**, and the contents of the `.p8` file (or upload the file). {% hint style="warning" %} Lost the `.p8`? It can't be downloaded again — revoke that key and generate a new one. {% endhint %} ## Google Play (Android) You'll create a **Google Cloud service account**, download its **JSON key**, and grant it access in the Play Console. ### Before you start * Your app already exists in Google Play Console. * Your Play Console payments profile and agreements are complete. * You can manage users in the Play Console (**Users and permissions**) — needed to invite the service account. ### Access level In **Google Cloud**, the service account needs only the **Google Play Developer API** (also listed as the **Google Play Android Developer API**) enabled in its project — no special Cloud IAM role. In the **Play Console**, grant the service account: * **View app information and download bulk reports** (account-level) — or **View app information** (for a single app) — so Amply can read your current products and prices. * **Manage store presence** — the permission that allows editing pricing for subscriptions and in-app products. You don't need "Manage orders and subscriptions" — that covers refunds and order management, not price edits. ### Steps 1. In the **Google Cloud Console**, create or select a project, create a **service account**, then create a **JSON key** for it and download the file. 2. In that same project, enable the **Google Play Developer API** (also shown as **Google Play Android Developer API**). 3. In **Play Console → Users and permissions**, choose **Invite new users** and enter the service account's email (the `client_email` from the JSON). 4. Grant the permissions above — account-wide, or for this specific app — then send the invite. 5. **Wait for the permissions to take effect.** This can take up to 24 hours, though it's often much faster. 6. In Amply, open your application's **Integrations** tab and paste the service-account JSON (or upload the file). ## After you connect Amply checks the credentials when you save. If it accepts them, you're ready to manage prices. If it rejects them, the cause is almost always one of: * **Apple** — the Key ID / Issuer ID don't match the `.p8`; the `.p8` is incomplete (copy the whole file, including the `BEGIN`/`END` lines); or the key's role is below App Manager. * **Google** — the service account isn't granted in the Play Console yet, or the permissions haven't propagated (wait, then try again); the Google Play Developer API isn't enabled; or **Manage store presence** wasn't granted. If it still fails after the permissions have propagated, re-save them in the Play Console and try again. ## Keeping credentials safe * Use a dedicated key / service account for Amply — don't reuse personal credentials. * Never commit your `.p8` or service-account JSON to source control. * Revoke and regenerate credentials when a team member leaves or a key may be exposed. Amply stores them encrypted and uses them only to read and update your store pricing. *** *Last reviewed: June 2026. Store consoles occasionally change their menus — if a label differs, look for the nearest equivalent.* # Creating a price change Build a price change in the three-step form, review the computed territory-by-territory prices, apply the draft to the store, and monitor the result. **Use this when** you're ready to push a new base price, percentage change, or matrix to the store for a specific product. **Don't use this when** you're still deciding on the target numbers — inspect current prices in [Compare](/price-management/comparing-prices) first, or shape the index in [Price indexes](/price-management/price-indexes). ## Prerequisites * The application is connected to App Store Connect or Google Play Console and its products are visible in Amply. * The product already has a current price in the base country (for Base-price method) or in every country you want to change (for Percentage method). * For iOS subscriptions: a decision about whether existing subscribers move to the new price or keep the current one. * For Android subscriptions: a product with a single base plan — multi-base-plan subscriptions are not supported. ## Step-by-step {% stepper %} {% step %} ### Open the form From **Price Management**, click **New Price Change** in the top right. If the project has more than one application, the active one is preselected — you can switch it at the top of the form. {% endstep %} {% step %} ### 1. Product Pick the product. The list shows subscriptions and in-app purchases for the selected application. For iOS, when the same product identifier exists as both a subscription and an in-app purchase, Amply picks the subscription. Click **Continue**. {% endstep %} {% step %} ### 2. Price details Fields depend on the pricing method you pick first. **Pricing method** * **Base price** — set one price in one country; Amply computes every other territory using a price index. * **Percentage** — set one ± number; Amply applies it to every territory's current store price. **If Base price:** * **Base Country** — the anchor country. Currency is inferred from it. * **Base Price** — on iOS, the field autocompletes the valid **Apple price points** (tier prices Apple accepts) for the selected country. On Android, any positive number is accepted. If the product already has a store price in the chosen base country, the field pre-fills it. * **Price Index** — the matrix of multipliers applied for every other territory. In-app purchases default to **Apple Store Matrix (IAP)**; subscriptions default to **App Store**. Change to any system or custom index. See [Price indexes](/price-management/price-indexes). **If Percentage:** * **Percentage change** — a signed number (e.g. `-10` for a 10% cut, `+15` for a 15% bump) applied to every current store price. **Start Date** When the new prices go live. On iOS, the earliest is tomorrow — Apple rejects same-day updates. On Google Play, the change is accepted immediately but can take several hours to appear on the listing. **Price change audience** (iOS subscriptions only) * **New subscribers only** — existing subscribers keep their current price. New subscribers get the new price. * **All subscribers** — existing subscribers move to the new price on the start date. Price decreases apply to everyone regardless of this setting. **Rounding Strategy** * **No Rounding** — raw computed price is used. * **Decimal Rounding** — round each price. Pick: * **Rounding Direction** — Round to nearest / Round up / Round down * **Rounding Profile** — Sharp (`.99`/`99`/`999`), Soft (`.95`/`95`/`950`), Round (`.00`/`00`/`000`), Half (`.50`/`50`/`500`) Click **Continue**. {% endstep %} {% step %} ### 3. Adjust Review the full per-territory table. Amply computes a new price for every territory the product is available in. Rows are grouped by continent; use **Expand all** / **Collapse all** to navigate. For each row you can: * Edit the **new price** inline to override the computed value. * Untick the row's checkbox to skip that territory. * Untick a continent header to skip every territory in that region. A banner at the top lists any territories where the store doesn't support pricing for this product; those are excluded automatically. Click **Create** at the bottom. The batch saves as a **Draft** and you land on the edit screen. {% endstep %} {% endstepper %} ## Drafts A draft is never sent to the store. You can leave it as long as you like; return to **Price Management**, filter by **Draft**, and open the row to resume editing. On the **Edit Draft** screen: * Change individual territory prices and skip flags. * **Delete** — remove the draft. * **Apply** — submit the batch to the store. The batch moves to **Pending** and you're taken to the detail view. Drafts with an expiration date show a reminder in the header; after that date they're cleared automatically. ## Monitoring a batch Open any non-draft batch from the history. The detail screen shows: * A status chip in the header: Pending, Sending, Completed, Incomplete, Failed, Cancelled, or Deferred. * Six counters: Total, Completed, Unchanged, Failed, Deferred, Pending. * A stacked progress bar colored by entry status. * A per-territory table: Territory, Original price, New price, Diff (%), Status, Attempts. While the batch is in flight, the page auto-refreshes every two seconds. Territories move through their own states: Pending → Sending → Completed, Failed, Skipped, Deferred, or Unchanged. An **Unchanged** entry means the computed price equalled the store's current price — no write was made. ### Recovering from failures When the batch is terminal (Completed, Incomplete, Failed, or Cancelled), two recovery actions may appear in the header: * **Retry failed (N)** — re-submit every Failed entry. Use this after transient store errors. The batch re-enters Sending. * **Resume now (N)** — push every Deferred entry immediately. Deferred usually means the store throttled the original attempt; this retries it right away. While the batch is still in flight (Pending or Sending), the header offers **Cancel batch** instead. Cancelling stops further submissions; already-synced prices stay live. A fourth action, **Save as custom index**, is shown for any Base-price batch that has entries — it doesn't depend on the batch being terminal. Use it to turn the per-territory matrix into a reusable index. See [Price indexes](/price-management/price-indexes#save-a-batch-as-an-index). ## Common mistakes * **Base price that isn't a valid Apple tier.** On iOS, the base price must match an Apple price point — use the autocomplete dropdown. * **Start date set to today.** Apple rejects same-day updates. Set tomorrow or later. * **All prices Unchanged.** The batch submitted fine but the computed prices matched current store prices exactly. Adjust your base price, percentage, or index. * **Started the batch before checking availability.** If a product isn't published in a country, that territory is skipped automatically and listed in the banner. Publish it in the store first if you want to include it. ## Related * [Price management overview](/price-management/price-management) — feature overview and status reference * [Price indexes](/price-management/price-indexes) — how the matrix used in "Base price" is defined * [Comparing prices](/price-management/comparing-prices) — preview current prices across products # Price indexes A **price index** is a table of per-territory multipliers. When you run a Base-price batch, Amply takes your base-country price and multiplies it by each territory's factor. Indexes come in two flavours — system (maintained by Amply) and custom (yours to edit). **Use this when** you want to reuse a pricing matrix across products or batches, import one from a spreadsheet, or inspect a system index. **Don't use this when** you only ever run Percentage-method batches — those ignore indexes. ## Prerequisites * Your plan includes custom price indexes. If the **Price Indexes** entry isn't in the left nav, check your plan. * The application is connected to App Store Connect or Google Play Console so territory codes resolve correctly in the factor table. ## Where to find it From the left nav under **Price Management**, click **Price Indexes**. The page heading reads **Custom Price Indexes**. The table lists every index available to the active project — both system and custom — with columns: Name, Countries, Created, Updated. Two controls above the list: * **Download template** — exports a blank CSV of every territory for a platform. Pick **All platforms**, **iOS only**, or **Android only**. * **New index** — choose **From CSV** (upload a filled-in template) or **Blank / manual** (open the editor). ## System vs custom | | System | Custom | | ------------- | --------------------------------- | -------- | | Maintained by | Amply | You | | Shown as | **System** label next to the name | No label | | Editable | No — view-only | Yes | | Deletable | No | Yes | | Duplicatable | Yes — creates a custom copy | Yes | Known system indexes in the dropdown include **Apple Store Matrix (IAP)** and **App Store**. Other system matrices may appear if Amply has provisioned them for your project — check the list. ## Managing custom indexes ### Create from scratch Click **New index** → **Blank / manual**. The editor opens with: * **Name** — a label you'll recognize in the dropdown later (for example, `2026 Q2 rollout — premium tier`). * **Platform** — All platforms, iOS only, or Android only. An iOS-only index is hidden when creating a batch for an Android product, and vice versa. * **Factor table** — one row per territory, pre-filled at `1.0`. Type a new multiplier: `1.5` means 50% above the base price, `0.8` means 20% below, `1.0` is parity. Every factor must be positive — saving is blocked until the warnings clear. Click **Create index** to save. ### Create from CSV 1. Click **Download template** and pick the platform. The CSV downloads as `amply-price-index-template--.csv`. 2. Fill in the factor column for each territory in a spreadsheet. 3. Back in the list, click **New index** → **From CSV** and upload. Amply parses the file and opens the editor with factors pre-filled — you can still tweak before saving. ### Duplicate Any row — system or custom — has a **Duplicate** action in its row menu. It opens the editor pre-filled with the original's factors and `(copy)` suffixed on the name. Use this to derive a custom variant of a system index. ### Edit Click the pencil icon on a custom row. System rows only offer a view-only dialog (the eye icon). The editor shows a **"referenced by N price changes"** banner when the index is currently used — edits to the index don't change prior batches, only future ones. Click **Save changes** when done. ### Delete Row menu → **Delete**. The request can fail — for example if the index is still referenced by a batch — and Amply surfaces the error in a toast. Rewrite or remove the offending batches first if that happens. ## Save a batch as an index Any Base-price batch with entries shows a **Save as custom index** button on its detail view. Amply derives an index from the per-territory prices the batch produced and opens the editor with: * A suggested name based on the product and date. * Platform compatibility inferred from the batch. * The factor table pre-filled. * Optional warnings if any territory couldn't be derived. Review, adjust, save. The result is a regular custom index you can use in future batches. Percentage-method batches don't produce an index — there's no per-territory factor matrix to derive. ## How factors are applied For a Base-price batch using index *I* in base country *C*: 1. Base price *P* is what you entered in the form. 2. For each territory *T* in *I*, the computed price is `P × I[T]`. 3. The result is rounded per your rounding settings (if any). 4. On iOS only, the result is snapped to the nearest valid Apple price point. Territories missing from *I* are skipped for that batch. The base country's own factor in *I*, if present, is ignored — the base price is used as-is. ## Common mistakes * **Wrong platform tag.** If an index doesn't show up in the dropdown, check its Platform — an iOS-only index is hidden for Android batches. * **Template mismatch.** Uploading an Android-only template into an iOS-only index produces rows the other platform doesn't support. Use **All platforms** if you want the index usable everywhere. * **Non-positive factor.** Zero or negative factors block saving. Keep every row at `1.0` or higher to include it at parity with the base; set lower (e.g. `0.9`) for a discount. * **Forgetting to update referenced batches.** Editing an index doesn't rewrite batches that already submitted — only future ones using it. ## Related * [Creating a price change](/price-management/creating-a-price-change) — where indexes are selected * [Comparing prices](/price-management/comparing-prices) — side-by-side view of current prices across products * [Price management overview](/price-management/price-management) — when to pick Base price vs Percentage # Comparing prices A side-by-side table of current store prices for up to three products across every territory they sell in, with inline editing and a per-product "Create Price Change" shortcut. **Use this when** you want to see two or three products' current prices next to each other — yearly vs monthly, an in-app purchase vs its subscription equivalent — or when you want to edit prices in a table and save the result as a draft batch. **Don't use this when** you already know the target prices for one product — open [Creating a price change](/price-management/creating-a-price-change) directly. ## Prerequisites * The application is connected to App Store Connect or Google Play Console and its products are visible in Amply. * The products you want to compare have at least one current store price. ## Where to find it From **Price Management**, click **Compare** in the top right. The heading reads **Compare Prices**, breadcrumb **Price Management → Compare**. ## Setting it up **Application** Pick the application at the top. Compare only works within a single application; it doesn't mix products from different apps. **Product slots** Add up to three products using the **+** column on the right side of the table. The picker groups products by **Subscriptions** and **In-App Purchases**. Each slot gets its own column colour so rows stay readable as you scan across. Every slot header has two icons: * **Star** — marks the **reference product**. Every other column shows its delta relative to this one. Click the star on another slot to move the reference. * **Close** — removes the product from the table. ## Reading the table The row set is the **union** of every country where any selected product has a price. Rows are grouped by continent and sorted alphabetically. Each slot cell shows the current price (inline-editable) with a small delta label above it. The colour follows the sign of the delta: * Positive (this slot's price is **above** the reference) — green. * Negative (this slot's price is **below** the reference) — red. * Near zero (within ±0.05%) — neutral. Edits are local to Compare. They seed the draft when you save, but they don't change anything in the store on their own. ## The "Compare by" toggle Above the table, pick how the delta is computed: * **%** — raw percentage difference between each slot's price and the reference's price, with no period normalization. * **/wk** — normalize each price to its weekly equivalent first, then compute the percentage delta. * **/mo** — normalize each price to its monthly equivalent. * **/yr** — normalize each price to its yearly equivalent. The `/wk`, `/mo`, `/yr` options are only available when every slot is a subscription — one-time products don't have a billing period to normalize over. Use these to compare, say, a monthly and an annual sub on equal terms. ## Turning a comparison into a draft Each product column has its own **Create Price Change** button. Clicking it opens a two-step dialog for that product: {% stepper %} {% step %} ### Settings * **Start date** — same constraints as a real batch (tomorrow or later on iOS). * **Audience** (iOS subscriptions only) — New subscribers only / All subscribers. * **Rounding Strategy** — No Rounding or Decimal Rounding. * **Rounding Direction** (if Decimal) — Round to nearest / Round up / Round down. * **Rounding Profile** (if Decimal) — Sharp / Soft / Round / Half. Click **Next** to review. {% endstep %} {% step %} ### Review The dialog applies the selected rounding to every current price you see in the Compare table (plus any inline edits you made) and shows the final per-territory values. Click **Create draft** to save. {% endstep %} {% endstepper %} The button creates a **Base-price** batch anchored in the **United States** — the US row supplies the base price, every other territory gets its exact value from the Compare table. No price index is used; the territory list is the set of literal prices from the table, rounded per your dialog settings. Amply confirms with a toast that includes a **review and apply** link to the new draft — click it to open the **Edit Draft** screen, where you can still edit individual territory prices or skip countries before applying. If you want a batch driven by a price index instead of by literal per-territory prices, start from **New Price Change** on the history screen — see [Creating a price change](/price-management/creating-a-price-change). ## Tips * **Pick the reference thoughtfully.** Every delta is relative to it — switching the reference re-colours the entire table. * **Yearly vs monthly.** Drop a yearly and a monthly sub into two slots, switch to `/mo`, and you'll see whether your yearly is priced above or below twelve monthly periods in every country. * **Inline edits don't modify the store.** Until you click **Create draft**, nothing is persisted. * **Stale-looking prices.** Compare reads the prices Amply knows about. If a batch recently completed, give it a moment to propagate. ## Related * [Creating a price change](/price-management/creating-a-price-change) — the full three-step form with index selection * [Price indexes](/price-management/price-indexes) — how a base-price + index batch computes territory prices * [Price management overview](/price-management/price-management) — where this screen lives # Installation How to add Amply to your mobile app. One dependency, three platforms — pick the tab that matches your stack. Installing Amply means adding a single package to your build config, then calling the SDK from your app's entry point. This page only covers the dependency step. Go to the platform-specific Quickstart once the package resolves. {% hint style="info" %} **Two ways to integrate Amply.** This guide is the **by-hand** path. The other is [**AI-assisted integration**](/getting-started/ai-assisted-integration): connect the Amply MCP and the `amply-integration` skill to your AI coding assistant (Claude Code or Codex CLI) and it installs the SDK, forwards the events Amply needs for targeting, and hands you a reviewable diff — the same result as the steps below, in one pass. {% endhint %} ## Current versions Other pages in this guide reference "the current version" — the table below is the single source of truth. When a new SDK ships, only this page needs updating. | Package | Version | | ----------------- | -------- | | iOS / Android SDK | `0.10.1` | | React Native SDK | `0.10.1` | ## Requirements | Platform | Minimum OS | Other | | ------------ | ---------------------- | --------------------------------------------------- | | iOS SDK | iOS 14.0 | Xcode 15+, Swift 5.9+ | | Android SDK | Android 5.0 (API 21) | Kotlin 1.9+, AGP 8.0+ | | React Native | RN 0.79+, Expo SDK 54+ | iOS 14+ / Android API 24+, New Architecture enabled | ## Credentials You need three values from the Amply dashboard before the SDK will run: * `appId` — your app's identifier (e.g., `com.acme.app`) * `apiKeyPublic` — short key used to identify your app * `apiKeySecret` — longer key used to sign requests Open the Amply dashboard, go to **Settings → API Keys**, and copy them into the config shown in the Quickstarts. ## Install {% tabs %} {% tab title="iOS (Swift)" %} ### CocoaPods Add to your `Podfile`: ```ruby pod 'AmplySDK', '~> 0.10.1' ``` Then install: ```bash pod install ``` Open the generated `.xcworkspace` in Xcode. ### Swift Package Manager In Xcode: **File → Add Package Dependencies…** and enter: ``` https://github.com/amply-tools/amply-sdk-ios ``` Pick the version rule (recommended: *Up to Next Major Version* from `0.10.1`) and add `AmplySDK` to your target. Or declare it in `Package.swift`: ```swift dependencies: [ .package(url: "https://github.com/amply-tools/amply-sdk-ios", from: "0.10.1") ] ``` ### Info.plist No mandatory entries. If you plan to read the advertising identifier (IDFA) for attribution, add `NSUserTrackingUsageDescription` to `Info.plist` and call the App Tracking Transparency prompt yourself — the SDK will pick up the resulting status. Continue with the [iOS Quickstart](/developer-guide/quickstart-ios) to wire the SDK into your `AppDelegate`. {% endtab %} {% tab title="Android (Kotlin)" %} ### Gradle (Kotlin DSL) Add to your app module's `build.gradle.kts`: ```kotlin dependencies { implementation("tools.amply:sdk-android:0.10.1") } ``` ### Gradle (Groovy) ```groovy dependencies { implementation 'tools.amply:sdk-android:0.10.1' } ``` ### Repositories The SDK ships to Maven Central. If your `settings.gradle.kts` already lists `mavenCentral()` (the default for new Android projects) you don't need to change anything: ```kotlin dependencyResolutionManagement { repositories { google() mavenCentral() } } ``` ### Permissions No permissions are required to initialize the SDK. `INTERNET` (already granted by default) is used to send events. If you want to collect the Google advertising ID for attribution, add: ```xml ``` Continue with the [Android Quickstart](/developer-guide/quickstart-android) to wire the SDK into your `Application` class. {% endtab %} {% tab title="React Native" %} ### npm / yarn ```bash yarn add @amplytools/react-native-amply-sdk ``` or ```bash npm install @amplytools/react-native-amply-sdk ``` ### Expo Amply ships an Expo config plugin. Add it to `app.json`: ```json { "expo": { "plugins": ["@amplytools/react-native-amply-sdk"] } } ``` Then run a prebuild so the native modules link: ```bash npx expo prebuild ``` ### Bare React Native Autolinking picks up the module after `yarn install`. On iOS you also need to install the pod: ```bash cd ios && pod install ``` No extra Gradle config is required on Android. See the [Requirements](#requirements) table above for minimum versions. Continue with the [React Native Quickstart](/developer-guide/quickstart-react-native) to initialize the SDK in your root component. {% endtab %} {% endtabs %} ## Related * [iOS Quickstart](/developer-guide/quickstart-ios) — first tracked event from a Swift app * [Android Quickstart](/developer-guide/quickstart-android) — first tracked event from a Kotlin app * [React Native Quickstart](/developer-guide/quickstart-react-native) — first tracked event from TypeScript * [iOS integration](/developer-guide/ios-integration) — deep links, session lifecycle, custom properties * [Android integration](/developer-guide/android-integration) — deep links, custom properties, log levels * [React Native integration](/developer-guide/react-native-integration) — listeners, snapshots, Expo specifics # Quickstart — iOS Install the Amply iOS SDK, initialize it with your API keys, and send your first event. You'll end with a tracked event visible in the Amply dashboard. This tutorial takes about ten minutes. It uses Swift and UIKit's `AppDelegate`. The same pattern works in SwiftUI — call the same initializer from the `App` struct's `init()`. **Prerequisites** * An iOS 14.0+ deployment target — see [Installation](/developer-guide/installation) for the full requirements matrix * An Amply dashboard account with `appId`, `apiKeyPublic`, and `apiKeySecret` (Settings → API Keys) * CocoaPods or Swift Package Manager set up in your project **You'll end with** * The SDK initialized on app launch * One custom event tracked from your code * That event showing up in the Amply dashboard's event log ## 1. Add the SDK Follow [Installation → iOS](/developer-guide/installation) to add the `AmplySDK` pod or Swift package. Come back here once `import AmplySDK` resolves cleanly. ## 2. Initialize on launch Initialize Amply in `AppDelegate.application(_:didFinishLaunchingWithOptions:)`. Constructing `Amply(config:)` starts the SDK — there is no separate `initialize()` call. {% code title="AppDelegate.swift" %} ```swift import UIKit import AmplySDK @main class AppDelegate: UIResponder, UIApplicationDelegate { static var amply: Amply? func application( _ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? ) -> Bool { let config = AmplyConfig( appId: "com.acme.app", apiKeyPublic: "YOUR_PUBLIC_KEY", apiKeySecret: "YOUR_SECRET_KEY", defaultConfig: nil ) AppDelegate.amply = Amply(config: config) AppDelegate.amply?.setLogLevel(level: "debug") return true } } ``` {% endcode %} `AmplyConfig` takes three required fields — `appId`, `apiKeyPublic`, `apiKeySecret` — plus an optional `defaultConfig` used for preloaded campaign content. Leave it `nil` for now. `setLogLevel(level: "debug")` prints SDK activity to the Xcode console while you're wiring things up. Remove or switch to `"warn"` before shipping. {% hint style="info" %} **SwiftUI?** Put the same `AmplyConfig` + `Amply(config:)` in your `App` struct's `init()` and store the instance on an `@StateObject` or singleton of your choice. {% endhint %} ## 3. Track your first event From anywhere in your app — a button handler, a view controller's `viewDidLoad`, a coordinator — call `track`: ```swift AppDelegate.amply?.track(event: "Signup", properties: ["plan": "pro"]) ``` `track(event:properties:)` takes an event name and an optional `[String: Any]` map of properties. Event names should be short and consistent (e.g., `Signup`, `Purchase`, `TrialStarted`). Properties go on the event for segmentation in the dashboard. ## 4. Manage the session lifecycle iOS doesn't emit the same lifecycle callbacks as Android, so Amply exposes three session methods you call yourself. Wire them to the standard `UIApplicationDelegate` hooks so sessions bookend real user activity. {% code title="AppDelegate.swift" %} ```swift func applicationDidBecomeActive(_ application: UIApplication) { AppDelegate.amply?.resumeSession() } func applicationDidEnterBackground(_ application: UIApplication) { AppDelegate.amply?.pauseSession() } func applicationWillTerminate(_ application: UIApplication) { AppDelegate.amply?.stopSession() } ``` {% endcode %} * `resumeSession()` — call when the app becomes active again * `pauseSession()` — call when the app enters background * `stopSession()` — call on terminate, or when you want to force-close the current session Skipping these won't crash the SDK, but session duration and session-scoped custom properties will be inaccurate. {% hint style="warning" %} Android auto-manages sessions via the process lifecycle. iOS does not — this step is required on iOS. {% endhint %} ## 5. Verify in the dashboard 1. Run the app on a simulator or device. 2. Trigger the code path that calls `track(event: "Signup", ...)`. 3. Open the Amply dashboard and go to **Events** (or the real-time event log for your app). 4. You should see an entry for `signup` with the `plan: pro` property within a few seconds. If the event doesn't appear, check: * The Xcode console (log level `"debug"`) for SDK errors * That `appId`, `apiKeyPublic`, and `apiKeySecret` match your dashboard app exactly * That the device has network connectivity — events are queued and retried, but the first event needs a live connection to prove the pipeline works ## What's next * [iOS integration](/developer-guide/ios-integration) — deep link handling, custom properties, user identification * [Concepts → Sessions and events](/concepts/sessions-and-events) — how events, properties, and datasets fit together * [Recipes — entry-based onboarding routing](/recipes/entry-based-onboarding-routing) — ready-made pattern for signup and onboarding flows ## Related * [Installation](/developer-guide/installation) — pod / SPM setup details * [Android Quickstart](/developer-guide/quickstart-android) — same flow on Android # Quickstart — Android Install the Amply Android SDK, initialize it with your API keys, and send your first event. You'll end with a tracked event visible in the Amply dashboard. This tutorial takes about ten minutes. It uses Kotlin and initializes the SDK in your `Application` class, which is the recommended entry point because it fires before any `Activity` starts. **Prerequisites** * A minSdk of 21 (Android 5.0) or higher — see [Installation](/developer-guide/installation) for the full requirements matrix * An Amply dashboard account with `appId`, `apiKeyPublic`, and `apiKeySecret` (Settings → API Keys) * Gradle configured to resolve from `mavenCentral()` **You'll end with** * The SDK initialized on app startup * One custom event tracked from your code * That event showing up in the Amply dashboard's event log ## 1. Add the SDK Follow [Installation → Android](/developer-guide/installation) to add `tools.amply:sdk-android` to your app module's dependencies (see [Installation — Current versions](/developer-guide/installation#current-versions) for the version to pin). Come back here once your build resolves. ## 2. Create (or open) your Application class If your project already has a custom `Application`, open it. If not, create one next to your `MainActivity`: {% code title="app/src/main/java/com/acme/app/AmplyApp.kt" %} ```kotlin package com.acme.app import android.app.Application import tools.amply.sdk.Amply import tools.amply.sdk.config.amplyConfig class AmplyApp : Application() { lateinit var amply: Amply private set override fun onCreate() { super.onCreate() val config = amplyConfig { api { appId = "com.acme.app" apiKeyPublic = "YOUR_PUBLIC_KEY" apiKeySecret = "YOUR_SECRET_KEY" } } amply = Amply(config, this) } } ``` {% endcode %} Register it in `AndroidManifest.xml`: ```xml ``` Constructing `Amply(config, this)` starts the SDK. There's no separate `initialize()` call. The `Application` instance is required so the SDK can observe the process lifecycle automatically (see step 4). {% hint style="info" %} The `amplyConfig { api { ... } }` DSL is the recommended way to build `AmplyConfig` — it's declarative and keeps credentials grouped. {% endhint %} ## 3. Track your first event From anywhere with access to the `Application` (or a DI-provided `Amply` instance), call `track`: ```kotlin val amply = (application as AmplyApp).amply amply.track(event = "Signup", properties = mapOf("plan" to "pro")) ``` `track(event, properties)` takes an event name and an optional `Map` of properties. Names should be short and consistent (e.g., `Signup`, `Purchase`, `TrialStarted`). Supported property value types: `String`, `Int`, `Long`, `Float`, `Double`, `Boolean`, `DateTimeValue`. From a `ViewModel` or `Activity`, inject the SDK instance rather than reaching through `application` — the approach above is just the shortest path to a first event. ## 4. Session lifecycle (nothing to do) On Android the SDK observes `ProcessLifecycleOwner` and manages sessions automatically: * A session starts the first time your process becomes foreground. * It pauses when the app goes to background and resumes when the user returns. * It ends after the configured inactivity timeout. You don't call `pauseSession()`, `resumeSession()`, or `stopSession()` on Android. (Those methods exist on iOS because UIKit doesn't give the SDK a process-level lifecycle hook.) ## 5. Turn on logs while you verify Before shipping, lower the log level. While wiring things up, turn it up: ```kotlin amply.setLogLevel("debug") ``` SDK output lands in Logcat under tags starting with `Amply`. Use the Logcat filter `tag:Amply` to see only SDK messages. Valid levels: `"none"`, `"error"`, `"warn"`, `"info"`, `"debug"`. ## 6. Verify in the dashboard 1. Run the app on an emulator or device. 2. Trigger the code path that calls `track(event = "Signup", ...)`. 3. Open the Amply dashboard and go to **Events** (or the real-time event log for your app). 4. You should see a `signup` entry with `plan: pro` within a few seconds. If nothing shows up: * Filter Logcat on `tag:Amply` and look for error lines * Confirm the values in `amplyConfig { api { ... } }` match the dashboard Settings → API Keys page exactly * Confirm the device has internet — the first event needs a successful round-trip to prove the pipeline works ## What's next * [Android integration](/developer-guide/android-integration) — deep links, custom properties, user IDs, ProGuard notes * [Concepts → Sessions and events](/concepts/sessions-and-events) — how events, properties, and datasets fit together * [Recipes — entry-based onboarding routing](/recipes/entry-based-onboarding-routing) — ready-made pattern for signup and onboarding flows ## Related * [Installation](/developer-guide/installation) — Gradle coordinates, minimum versions, permissions * [iOS Quickstart](/developer-guide/quickstart-ios) — same flow on iOS (note: iOS requires manual session calls) # Quickstart — React Native Install the Amply React Native SDK, initialize it with your API keys, and send your first event. You'll end with a tracked event visible in the Amply dashboard. This tutorial takes about ten minutes. It uses TypeScript and works the same way for bare React Native and Expo projects. The SDK runs on the native side — `Amply.initialize()` is async because it hands off to iOS and Android at startup. **Prerequisites** * React Native 0.79+ with the New Architecture enabled (or Expo SDK 54+) — see [Installation](/developer-guide/installation) for the full requirements matrix * Node 18+ and either npm or yarn * An Amply dashboard account with `appId`, `apiKeyPublic`, and `apiKeySecret` (Settings → API Keys) **You'll end with** * The SDK initialized when your app mounts * One custom event tracked from TypeScript * That event showing up in the Amply dashboard's event log ## 1. Add the SDK Follow [Installation → React Native](/developer-guide/installation) to add `@amplytools/react-native-amply-sdk`. For Expo apps, make sure you've added the config plugin and run `npx expo prebuild`. For bare RN, run `pod install` in `ios/`. Come back here once `import Amply from '@amplytools/react-native-amply-sdk'` resolves. ## 2. Initialize on app start Initialize Amply once, as early as possible — typically in your root `App` component, inside a `useEffect` that runs on mount. `initialize()` is async and returns a `Promise`; await it (or chain `.then`) before calling any other SDK method. {% code title="App.tsx" %} ```typescript import React, {useEffect, useState} from 'react'; import {Text, View} from 'react-native'; import Amply from '@amplytools/react-native-amply-sdk'; export default function App(): React.JSX.Element { const [ready, setReady] = useState(false); useEffect(() => { Amply.initialize({ appId: 'com.acme.app', apiKeyPublic: 'YOUR_PUBLIC_KEY', apiKeySecret: 'YOUR_SECRET_KEY', logLevel: 'debug', }) .then(() => setReady(true)) .catch(error => console.error('Amply init failed', error)); }, []); return ( {ready ? 'Amply ready' : 'Initializing…'} ); } ``` {% endcode %} The `AmplyInitializationConfig` fields you'll use here: | Field | Type | Required | Notes | | ---------------- | -------------------------------------------------- | -------- | --------------------------------------------------------- | | `appId` | `string` | yes | Your app identifier | | `apiKeyPublic` | `string` | yes | Public key from the dashboard | | `apiKeySecret` | `string` | no | Secret key from the dashboard | | `configBaseUrl` | `string` | no | Point campaign config at another stack (development only) | | `backendBaseUrl` | `string` | no | Point event delivery at another stack (development only) | | `logLevel` | `'none' \| 'error' \| 'warn' \| 'info' \| 'debug'` | no | Print SDK activity to Metro console | `logLevel: 'debug'` is the quickest way to see what the SDK is doing in Metro. Switch to `'warn'` or `'none'` before shipping. Campaign config and event delivery are served from **different hosts**, so pointing the app at a staging or local stack takes both `configBaseUrl` and `backendBaseUrl`. Setting only one leaves the other half of the traffic on production. {% hint style="info" %} `Amply.isInitialized()` is synchronous and returns `true` after the promise resolves. Use it from screens that mount before init completes. {% endhint %} ## 3. Track your first event Call `Amply.track()` from any component, hook, or handler. It takes a payload object with a `name` and an optional `properties` map. ```typescript import Amply from '@amplytools/react-native-amply-sdk'; async function onSignupPress() { await Amply.track({ name: 'Signup', properties: {plan: 'pro'}, }); } ``` `track()` returns a `Promise`. You can `await` it when you want to be sure the event was handed to the native side (e.g., before navigating), or fire-and-forget for UI events. Property values must be strings, numbers, or booleans. Keep event names short and consistent — the dashboard segments by event name, so a typo becomes a different event. ## 4. Identify the user (optional but recommended) Once you know who the user is — after signup, login, or restoring a session — tell Amply: ```typescript Amply.setUserId('user-123'); Amply.setCustomProperties({plan: 'pro', onboarded: true}); ``` `setUserId()` is fire-and-forget (no promise). Pass `null` to clear the user ID on sign-out. `setCustomProperties()` accepts a `Record` and merges into whatever is already stored. ## 5. Verify in the dashboard 1. Run the app on an iOS simulator, Android emulator, or real device (`yarn ios` / `yarn android`, or `npx expo run:ios` / `run:android`). 2. Trigger the code path that calls `Amply.track({name: 'Signup', ...})`. 3. Open the Amply dashboard and go to **Events**. 4. Watch for a `signup` entry with `plan: pro` — it should arrive within a few seconds. If you don't see it: * Check the Metro console for `[Amply]` log lines (visible when `logLevel: 'debug'` is set) * Confirm `appId` / `apiKeyPublic` / `apiKeySecret` match the dashboard Settings → API Keys page exactly * Confirm the device has network connectivity — the first event needs a successful round-trip to prove the pipeline works * On Expo, confirm you re-ran `npx expo prebuild` after adding the plugin ## What's next * [React Native integration](/developer-guide/react-native-integration) — deep link listeners, system events, snapshots, hooks * [Concepts → Sessions and events](/concepts/sessions-and-events) — how events, properties, and datasets fit together * [Recipes — entry-based onboarding routing](/recipes/entry-based-onboarding-routing) — ready-made pattern for signup and onboarding flows ## Related * [Installation](/developer-guide/installation) — npm package, Expo plugin, version requirements * [iOS Quickstart](/developer-guide/quickstart-ios) — native Swift flow * [Android Quickstart](/developer-guide/quickstart-android) — native Kotlin flow # iOS integration In plain English: this page is a collection of how-tos for the Amply iOS SDK beyond "just get it running." It covers session control, deeplink scheme setup, app lifecycle bridging, and the preflight pattern for asking permissions the right way. A PM can skim the section headings to know which knobs exist; an engineer copies the Swift snippets. **Use this when** you already have the iOS SDK initialized and you need to wire up a specific flow (deeplinks, lifecycle, permissions). **Don't use this when** you haven't finished the Quickstart yet — start there. ## Before you start * iOS SDK initialized in `AppDelegate` (see [iOS quickstart](/developer-guide/quickstart-ios)). * A strong reference held to your `Amply` instance and any listener adapters on your own side, so they stay alive for the lifetime of the app. ## Managing the session manually On iOS the SDK does not auto-track app foreground/background. You call the lifecycle methods yourself. This is different from Android, where lifecycle is automatic. **Signatures** (from `Amply`): ```swift func pauseSession() func resumeSession() func stopSession() ``` Wire them up in your `AppDelegate`: ```swift // AppDelegate.swift import AmplySDK func applicationDidBecomeActive(_ application: UIApplication) { AppDelegate.amply?.resumeSession() } func applicationDidEnterBackground(_ application: UIApplication) { AppDelegate.amply?.pauseSession() } func applicationWillTerminate(_ application: UIApplication) { AppDelegate.amply?.stopSession() } ``` If you use `UISceneDelegate`, bridge the same calls from `sceneDidBecomeActive(_:)` and `sceneDidEnterBackground(_:)` instead. If you need to distinguish "brief interruption" (incoming call, control center, app switcher preview) from "user left the app," call `pauseSession()` from `applicationWillResignActive(_:)` instead of `applicationDidEnterBackground(_:)`. The trade-off: session timing is more sensitive to transient interruptions, but you capture the moment attention leaves the screen. ### When to pause vs. stop * `pauseSession()` — app went to background. Session can resume when the user returns. * `resumeSession()` — app returned to foreground before the session timeout. * `stopSession()` — force-end the current session (for example, user logs out). ## Registering your deeplink scheme The SDK will deliver campaign deeplinks to your app, but the scheme still needs to be declared in `Info.plist` so iOS routes URLs to you. ```xml CFBundleURLTypes CFBundleTypeRole Editor CFBundleURLName com.example.yourapp CFBundleURLSchemes yourapp ``` Use the same scheme when you author deeplink URLs in the Amply dashboard (for example `yourapp://promo/summer`). ## Receiving campaign deeplinks Register a listener after SDK init. The callback returns a `Bool` — `true` if you handled the URL, `false` to let the system default handler try. **Signature:** ```swift func registerDeepLinkListener(listener: DeepLinkListener) -> ListenerToken // DeepLinkListener.onDeepLink(url: String, info: [String: Any]) -> Bool ``` ```swift // DeepLinkAdapter.swift import AmplySDK final class DeepLinkAdapter: NSObject, DeepLinkListener { func onDeepLink(url: String, info: [String: Any]) -> Bool { guard let parsed = URL(string: url) else { return false } if parsed.scheme == "yourapp", parsed.host == "promo" { let promoId = parsed.lastPathComponent Router.shared.showPromo(id: promoId) return true } return false } } // AppDelegate.swift private let deepLinkAdapter = DeepLinkAdapter() private var deepLinkToken: ListenerToken? // Keep the adapter retained on the AppDelegate, not as a local — and keep the token with it. deepLinkToken = amply?.registerDeepLinkListener(listener: deepLinkAdapter) ``` {% hint style="warning" %} **Store the token.** Registering returns a `ListenerToken`, and that token — not the adapter object — is what detaches the listener later via `removeDeepLinkListener(token:)`. A listener registered once at launch and kept for the life of the app never needs detaching, so storing the token costs nothing. Anything shorter-lived does need it: a listener left attached after its owner is gone keeps that owner alive and the SDK goes on calling it. {% endhint %} ## Universal Links Amply deeplinks are delivered through the SDK's listener regardless of scheme format. If you also want to handle Universal Links (`https://yourapp.com/...`) tapped from outside a campaign, use the standard iOS entry point: ```swift // AppDelegate.swift func application( _ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void ) -> Bool { guard userActivity.activityType == NSUserActivityTypeBrowsingWeb, let url = userActivity.webpageURL else { return false } Router.shared.handle(url: url) return true } ``` Track the hit through Amply if it matters for targeting: ```swift AppDelegate.amply?.track( event: "UniversalLinkOpened", properties: ["url": url.absoluteString] ) ``` ## Push notification preflight popup Asking iOS for push permission directly means a single "Allow / Don't Allow" dialog with no second chance. The common pattern is to show a soft-preflight popup via an Amply campaign first, then only call `UNUserNotificationCenter` for users who tap "Sure." High-level flow: 1. Track an event at a good moment, for example `OnboardingCompleted`. 2. In the Amply dashboard, target a popup campaign at that event. 3. The popup's primary button opens a deeplink like `yourapp://permissions/push`. 4. Your deeplink handler calls `requestAuthorization`. ```swift // DeepLinkAdapter.swift (extended) func onDeepLink(url: String, info: [String: Any]) -> Bool { guard let parsed = URL(string: url) else { return false } if parsed.host == "permissions", parsed.lastPathComponent == "push" { UNUserNotificationCenter.current().requestAuthorization( options: [.alert, .badge, .sound] ) { granted, _ in AppDelegate.amply?.track( event: granted ? "PushPermissionGranted" : "PushPermissionDenied" ) } return true } return false } ``` For the full recipe including copy tips and retry cadence, see [Soft push permission](/recipes/soft-push-permission). ## Listening to SDK system events Useful during development to see when config loads, when sessions start, and which campaigns evaluate. **Signature:** ```swift func setSystemEventsListener(listener: SystemEventsListener) -> ListenerToken // SystemEventsListener.onEvent(event: EventInterface) ``` ```swift final class SystemEventsAdapter: NSObject, SystemEventsListener { func onEvent(event: EventInterface) { print("[Amply] \(event.name) \(event.properties)") } } private let systemEventsAdapter = SystemEventsAdapter() private var systemEventsToken: ListenerToken? systemEventsToken = amply?.setSystemEventsListener(listener: systemEventsAdapter) ``` Hold the adapter on the `AppDelegate` or another long-lived owner, and hold the token alongside it — `clearSystemEventsListener(token:)` takes the token, not the adapter. ## Log level ```swift amply?.setLogLevel(level: "debug") // 'none' | 'error' | 'warn' | 'info' | 'debug' ``` Leave it at `warn` or lower in production builds. ## ATT and IDFA The SDK reads IDFA when App Tracking Transparency has been granted. Prompting for ATT is your app's responsibility: ```swift import AppTrackingTransparency ATTrackingManager.requestTrackingAuthorization { _ in // SDK will pick up IDFA on the next dataset read. } ``` Request ATT on a meaningful screen, not immediately on launch — Apple rejects apps that prompt before context is established. ## Related * [iOS quickstart](/developer-guide/quickstart-ios) — initial setup, not covered here. * [Tracking events](/developer-guide/tracking-events) — payload shapes and common patterns. * [Handling deeplinks](/developer-guide/handling-deeplinks) — cross-platform deeplink routing patterns. * [Soft push permission](/recipes/soft-push-permission) — full preflight recipe. * [SDK reference: iOS](/reference/sdk-ios) — full method list. # Android integration In plain English: this page is a collection of how-tos for the Amply Android SDK beyond "just get it running." It covers where to initialize, deeplink intent filters, lifecycle (the SDK handles this for you), and the permissions that affect what data the SDK can collect. A PM can skim headings to understand which knobs exist; an engineer copies the Kotlin snippets. **Use this when** the Android SDK is initialized and you need to wire up a specific flow. **Don't use this when** you haven't finished the Quickstart yet — start there. ## Before you start * A minSdk of 21 (Android 5.0) or higher — see [Installation](/developer-guide/installation) for the full requirements matrix. * An `Application` subclass — create one if you don't already have it. ## Initialize in your Application class The SDK needs the `Application` instance because it hooks Android's lifecycle to auto-manage sessions. This is the main difference from iOS, where you call `pauseSession` / `resumeSession` yourself. **Signatures** (from `Amply`): ```kotlin // Android Amply(config: AmplyConfig, application: Application) ``` ```kotlin // MyApplication.kt import android.app.Application import tools.amply.sdk.Amply import tools.amply.sdk.config.amplyConfig class MyApplication : Application() { lateinit var amply: Amply private set override fun onCreate() { super.onCreate() val config = amplyConfig { api { appId = "your.app.id" apiKeyPublic = "your_public_key" apiKeySecret = "your_secret_key" } } amply = Amply(config, this) } } ``` Register it in `AndroidManifest.xml`: ```xml ``` ### Accessing the instance Expose it through the `Application` context: ```kotlin // Anywhere with a Context val amply = (context.applicationContext as MyApplication).amply amply.track("ScreenViewed") ``` Consider wrapping this in a small helper (`App.amply(context)`) so the cast doesn't leak through your codebase. ## Lifecycle is automatic Once the SDK has your `Application`, it listens to process lifecycle events and manages sessions for you. You do **not** need to call `pauseSession`, `resumeSession`, or `stopSession` in `onPause`/`onStop` — those methods don't exist on the Android SDK. What this means in practice: * Session starts the first time your app enters the foreground after init. * Session pauses shortly after the last Activity leaves the foreground. * A new session begins when the user returns after the timeout. ## Registering deeplink intent filters The SDK delivers campaign deeplinks to your listener regardless of scheme, but Android still needs to know how to route URLs from outside your process (notification taps, browser handoff). Declare an intent filter on the Activity that should receive them. ```xml ``` Use the same scheme (`yourapp://`) when authoring campaign deeplink URLs in the Amply dashboard. ## Receiving campaign deeplinks Register a listener after SDK init. Return `true` if you handled the URL, `false` to fall through. **Signature:** ```kotlin fun registerDeepLinkListener(listener: DeepLinkListener): ListenerToken // DeepLinkListener.onDeepLink(url: String, info: Map): Boolean ``` `DeepLinkListener` is a plain interface, not a `fun interface`, so pass an object — a lambda will not compile. ```kotlin // MyApplication.onCreate() val deepLinkToken = amply.registerDeepLinkListener(object : DeepLinkListener { override fun onDeepLink(url: String, info: Map): Boolean = when { url.startsWith("yourapp://promo/") -> { val promoId = url.removePrefix("yourapp://promo/") Router.openPromo(this@MyApplication, promoId) true } else -> false } }) ``` Keep `deepLinkToken` — it is what detaches the listener via `removeDeepLinkListener(token)`. A listener registered in `Application.onCreate` and kept for the life of the process never needs detaching; one owned by an `Activity` or a feature module does. ### Handling external deeplinks When the user taps a URL in another app, Android delivers it as an `Intent` to your declared Activity. Amply's listener handles campaign-triggered deeplinks; external ones still go through standard `Intent` handling: ```kotlin // MainActivity.kt override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) intent?.data?.let { uri -> handleUri(uri) } } override fun onNewIntent(intent: Intent) { super.onNewIntent(intent) intent.data?.let { uri -> handleUri(uri) } } private fun handleUri(uri: Uri) { // Your navigation } ``` ## Permissions ### Advertising ID (optional) To collect the Google Advertising ID, add the dependency: ```kotlin // app/build.gradle.kts dependencies { implementation("com.google.android.gms:play-services-ads-identifier:18.0.1") } ``` Starting with Android 13, the Play Services library also requires a manifest permission, which is added automatically by the library's manifest merger. No further code is needed — the SDK picks up the ID when available. ### Internet The SDK requires `android.permission.INTERNET`, which is included by default in apps targeting recent SDK versions. Verify it's not stripped by a restrictive manifest. ## Listening to SDK system events Useful during development to see when config loads, when sessions start, and which campaigns evaluate. **Signature:** ```kotlin fun setSystemEventsListener(listener: SystemEventsListener): ListenerToken // SystemEventsListener.onEvent(event: EventInterface) ``` ```kotlin val systemEventsToken = amply.setSystemEventsListener(object : SystemEventsListener { override fun onEvent(event: EventInterface) { Log.d("Amply", "${event.name} ${event.properties}") } }) ``` `clearSystemEventsListener(token)` takes the token, not the listener. ## Log level ```kotlin amply.setLogLevel("debug") // 'none' | 'error' | 'warn' | 'info' | 'debug' ``` Leave it at `warn` or lower in production builds. ## Push notification preflight popup Asking Android 13+ for `POST_NOTIFICATIONS` directly means a single dialog. The pattern most apps use is a soft-preflight popup via an Amply campaign, which routes to a deeplink that triggers the system permission. Handle it as a branch **inside the listener you already registered above** — do not register a second one, since registration appends rather than replaces. ```kotlin override fun onDeepLink(url: String, info: Map): Boolean = when { url == "yourapp://permissions/push" -> { requestPostNotificationsPermission() true } // ...your other routes else -> false } ``` For the full recipe, see [Soft push permission](/recipes/soft-push-permission). ## Related * [Android quickstart](/developer-guide/quickstart-android) — initial setup, not covered here. * [Tracking events](/developer-guide/tracking-events) — payload shapes and common patterns. * [Handling deeplinks](/developer-guide/handling-deeplinks) — cross-platform deeplink routing patterns. * [Soft push permission](/recipes/soft-push-permission) — full preflight recipe. * [SDK reference: Android](/reference/sdk-android) — full method list. # React Native integration In plain English: this page is a collection of how-tos for the Amply React Native SDK beyond "just get it running." It covers peer dependencies, the iOS pod install step, Android autolinking, using the `useAmplySystemEvents` hook, cleaning up listeners so you don't leak memory, and handling re-initialization when the JS bundle reloads. A PM can skim the headings; an engineer copies the TypeScript snippets. **Use this when** the React Native SDK is installed and you need to wire a specific flow. **Don't use this when** you haven't finished the Quickstart yet — start there. ## Before you start * React Native 0.79+, Expo SDK 54+ (or bare RN 0.79+) — see [Installation](/developer-guide/installation) for the full requirements matrix. * New Architecture enabled (the SDK uses the new native module system). * Node 18+. ## Peer dependencies and install The SDK requires `react >=18.2.0`, `react-native >=0.79.0`, and `expo >=54.0.0` as peer dependencies — make sure your app has them, then install: ```bash npm install @amplytools/react-native-amply-sdk ``` ## iOS: run pod install After installing the npm package, refresh the iOS native project. This links the native iOS SDK into your app. ```bash cd ios pod install cd .. ``` Run this every time you change the installed npm version of the SDK. ## Android: autolinking is automatic On Android there is no manual Gradle edit. The SDK ships a `react-native.config.js` entry that React Native's autolinking picks up on the next build. Just rebuild: ```bash npx react-native run-android ``` If you use Expo with `expo prebuild`, the SDK's config plugin registers the native package for you during prebuild. ## Initialize once, early Call `initialize` once, as close to app start as possible. The function returns a Promise that resolves when the native SDK is ready. **Signature:** ```ts Amply.initialize(config: AmplyInitializationConfig): Promise type AmplyInitializationConfig = { appId: string; apiKeyPublic: string; apiKeySecret?: string | null; endpoint?: string | null; defaultConfig?: string | null; debug?: boolean | null; logLevel?: LogLevel | null; }; ``` ```tsx // App.tsx import {useEffect} from 'react'; import Amply from '@amplytools/react-native-amply-sdk'; export default function App() { useEffect(() => { Amply.initialize({ appId: 'com.example.app', apiKeyPublic: 'pk_...', apiKeySecret: 'sk_...', logLevel: 'warn', }).catch(err => console.warn('[Amply] init failed', err)); }, []); return ; } ``` `Amply.isInitialized()` returns `true` synchronously once `initialize` has resolved. ### Custom property value types RN custom properties accept `string | number | boolean` only. The iOS and Android native SDKs accept more types — stick to primitives on React Native. ## Re-init on Fast Refresh / JS reload Pressing R in Metro re-runs your JS bundle but the native side stays alive. The native SDK remains initialized across JS reloads. Guarding your init is optional but keeps logs clean: ```ts if (!Amply.isInitialized()) await Amply.initialize(config); ``` On a cold launch, both JS and native start fresh — always call `initialize` on mount. ## Listening to system events System events are SDK lifecycle signals: config loaded, session started, campaign evaluated. Two APIs are available. ### Option 1: the hook (good for debug UI) **Signature:** ```ts useAmplySystemEvents(options?: { maxEntries?: number; // default 50 dedupe?: boolean; // default true onEvent?: (event: EventRecord) => void; }): {events: EventRecord[]; reset: () => void}; ``` ```tsx import {useAmplySystemEvents} from '@amplytools/react-native-amply-sdk'; function DebugPanel() { const {events, reset} = useAmplySystemEvents({maxEntries: 20}); return ( {events.map(e => {e.name} @ {e.timestamp})}