> 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/referral-at-positive-moment.md).

# 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.md) — the same pattern for store ratings
* [Custom popups](/user-guide/custom-popups.md) — for a lighter popup variant before the full invite screen
* [Creating a campaign](/user-guide/creating-a-campaign.md) — building the event-triggered campaign
* [Tracking events](/developer-guide/tracking-events.md) — firing `PositiveMoment` consistently
* [Campaign delivery](/concepts/campaign-delivery.md) — once-per-user frequency caps
* [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/referral-at-positive-moment.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.