> 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