> 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/recipes/entry-based-onboarding-routing.md).

# 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/<flow>` 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.md) — building the campaigns used here
* [Targeting an audience](/user-guide/targeting-an-audience.md) — how the source condition is expressed
* [Managing deeplinks](/user-guide/managing-deeplinks.md) — registering the onboarding routes
* [User attributes](/concepts/user-attributes.md) — why `acquisition_source` belongs on the user, not the event
* [Handling deeplinks](/developer-guide/handling-deeplinks.md) — the deeplink listener on the SDK side
* [AI-assisted integration](/getting-started/ai-assisted-integration.md) — describe this campaign in plain language and have your AI assistant build it


---

# 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/recipes/entry-based-onboarding-routing.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.