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.

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

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.

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.

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 — the developer side: registering a listener and routing the URL.

• Campaign actions — when to pick one action type over another.

• Testing and rollout — how to validate a campaign before it goes to all users.

• Campaigns — full reference on campaign structure.