> For the complete documentation index, see [llms.txt](https://docs.amply.tools/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amply.tools/user-guide/managing-deeplinks.md).

# 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.md).
* 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.md#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.md) — the developer side: registering a listener and routing the URL.
* [Campaign actions](/concepts/campaign-actions.md) — when to pick one action type over another.
* [Testing and rollout](/user-guide/testing-and-rollout.md) — how to validate a campaign before it goes to all users.
* [Campaigns](/user-guide/campaigns.md) — full reference on campaign structure.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amply.tools/user-guide/managing-deeplinks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.