> 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/feature-wall-contextual-paywall.md).

# Feature-wall contextual paywall

Show a paywall tailored to the specific Pro feature the user just tried to use, instead of a generic one.

**Use this when** your product has several distinct Pro features and users try different ones; a single headline paywall underserves all of them. **Don't use this when** there is only one Pro feature worth selling; the generic paywall already talks about it.

## Goal

A generic "Upgrade to Pro" paywall has to speak to everyone, so it speaks to nobody. The user who just tapped "Export to PDF" is not shopping for the abstract idea of premium — they want to export a PDF right now. This recipe intercepts the feature tap, fires a paywall whose hero section is about that exact feature, and preserves the user's intent to complete the export on conversion.

## Setup

The recommended primary shape is a **single campaign** that handles every gated feature and lets the app pick the matching paywall screen locally. It keeps the dashboard small even when you ship more Pro features. (See [Variants](#variants) for a per-feature alternative.)

### In the dashboard

* Create one campaign `feature-wall`.
* Trigger: event `FeatureGateTriggered`. No property filter on `feature` — you will branch in the app.
* Conditions: `subscription_status = "free"`.
* Action: fire `yourapp://paywall/feature-wall?feature={{feature}}`. The app reads the `feature` query parameter and chooses the right paywall screen.
* Frequency: unlimited — the user keeps hitting features; keep offering the relevant paywall.
* On conversion, resume the blocked action (see engineering hand-off).

### In the app (engineering hand-off)

* On a Pro feature tap, track the gate event with a `feature` property instead of showing a generic paywall:

  ```typescript
  await Amply.track({
    name: 'FeatureGateTriggered',
    properties: { feature: 'pdf_export', source_screen: 'report_detail' }
  });
  ```
* Register a single deeplink handler for `yourapp://paywall/feature-wall`. Read the `feature` query parameter and route to the matching paywall screen locally.
* Ship each contextual paywall screen in the build before the campaign goes live. The deeplink cannot introduce new screens.
* When the user converts, resume the feature action the user originally tapped. Do not dump them back on the home screen.

## How it runs

1. Free user taps "Export to PDF" on a report screen.
2. App fires `FeatureGateTriggered { feature: "pdf_export", source_screen: "report_detail" }`.
3. Amply evaluates event-triggered campaigns. `feature-wall` matches.
4. Amply fires `yourapp://paywall/feature-wall?feature=pdf_export`. The app reads `feature=pdf_export` and opens the PDF-export paywall screen with its own hero and preview.
5. User taps subscribe, completes purchase, `subscription_status` becomes `"pro"`.
6. App returns the user to the report screen and completes the export automatically.
7. A different free user taps "Offline mode." Same flow — `feature-wall` matches again, the deeplink carries `feature=offline_mode`, and the app opens the offline-mode paywall screen instead.

## Variants

If you need to target or schedule paywalls per feature independently — for example, running a limited-time discount only on the export-to-PDF paywall — use one campaign per feature:

* `feature-wall-pdf-export`, `feature-wall-offline-mode`, `feature-wall-custom-themes`.
* Each campaign triggers on `FeatureGateTriggered` with a `feature = "pdf_export"` property filter and fires its own deeplink (`yourapp://paywall/pdf-export`, etc.).
* Each contextual paywall can be activated, cancelled, or re-audienced independently.

This scales poorly as the Pro feature set grows — prefer the single-campaign variant unless you need per-feature control.

## Metrics to watch

* Conversion rate per feature gate. Compare to the generic paywall baseline — expect significant lift on the features users actually reach for.
* Gate-to-convert time. Contextual paywalls usually convert faster because the intent is already there.
* Top-converting features. This data tells you which Pro features to invest more in.
* Post-purchase action completion. If most converters never actually export a PDF after subscribing, the intent-preservation path is broken.

## Related

* [Paywall versioning](/recipes/paywall-versioning.md) — shipping and testing each contextual paywall
* [Second-chance paywall](/recipes/second-chance-paywall.md) — complementary, triggered by session count instead of feature intent
* [Campaigns](/user-guide/campaigns.md) — configuring event-triggered campaigns
* [Tracking events](/developer-guide/tracking-events.md) — the `FeatureGateTriggered` pattern
* [Handling deeplinks](/developer-guide/handling-deeplinks.md) — resuming the gated action after conversion
* [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/feature-wall-contextual-paywall.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.