Blended CPI, Install to Trial, acquisition cohort report, Meta trial conversions

content/docs/dashboard/charts/blended-cpi.mdx

@@ -0,0 +1,23 @@
+---
+title: "Blended CPI"
+description: "Learn what the Blended CPI chart measures and when to use it."
+---
+<Frame>![Blended CPI chart](/images/charts/blended-cpi.jpg)</Frame>
+
+## What it shows
+
+Blended CPI shows your total ad spend across all campaigns divided by all new users, paid and organic.
+
+## How to use it
+
+Use it to see what an install costs you overall, counting the organic installs that paid acquisition may also be driving.
+
+## Good to know
+
+Blended CPI divides by installs, which web platforms don't report, so treat it as mobile-only. Stripe apps never see it. Paddle, promotional, and web checkout apps may still list it in the chart picker, where it has nothing meaningful to divide by.
+
+Blended CPI is a single blended figure and intentionally has no breakdown. For cost per install per campaign, use the acquisition cohort report, which divides spend by MMP-matched installs instead of by every install.
+
+Because values are cohorted by install date, the chart never uses an interval finer than a week while the interval is set to auto. A long enough range still resolves to monthly, and picking an interval yourself overrides it.
+
+Advertising charts appear once performance marketing is enabled for your app. See [Meta Ads](/integrations/meta-ads).

content/docs/dashboard/charts/index.mdx

@@ -32,6 +32,7 @@ Currently, we offer the following charts:
 #### Subscription Charts
 - [**Active Subscriptions**](/dashboard/charts/active-subscriptions): Count of unexpired, paid subscriptions.
 - [**Paid Conversion**](/dashboard/charts/paid-conversion): Percent of installs who became paying users.
+- [**Install to Trial**](/dashboard/charts/install-to-trial): Percent of installs who started a trial.
 - [**New Trials**](/dashboard/charts/new-trials): Trial starts, cohorted by trial start date.
 - [**Trial Conversion**](/dashboard/charts/trial-conversion): Percentage of trials that converted to paid subscriptions.
 - [**New Subscriptions**](/dashboard/charts/new-subscriptions): New subscriptions, cohorted by subscription start date.
@@ -61,6 +62,7 @@ Currently, we offer the following charts:
 - [**CPT (Cost per Trial)**](/dashboard/charts/cpt): Ad spend per trial start.
 - [**CPP (Cost per Paid User)**](/dashboard/charts/cpp): Ad spend per new paying user.
 - [**Blended CPT**](/dashboard/charts/blended-cpt): Total ad spend divided by all trial starts, paid and organic.
+- [**Blended CPI**](/dashboard/charts/blended-cpi): Total ad spend divided by all new users, paid and organic.
 
 ### Filtering chart data
 To filter data on a chart, **click** the **Filter** button at the top right:

content/docs/dashboard/charts/install-to-trial.mdx

@@ -0,0 +1,19 @@
+---
+title: "Install to Trial"
+description: "Learn what the Install to Trial chart measures and when to use it."
+---
+<Frame>![Install to Trial chart](/images/charts/install-to-trial.jpg)</Frame>
+
+## What it shows
+
+Install to Trial shows the percentage of installs that started a trial.
+
+## How to use it
+
+Use this chart to see how well new users move into a trial. It is the step before [Paid Conversion](/dashboard/charts/paid-conversion), which measures how many installs went all the way to paying.
+
+## Good to know
+
+Install to Trial divides by installs, which web platforms don't report, so treat it as mobile-only. Stripe apps never see it. Paddle, promotional, and web checkout apps may still list it in the chart picker, where it has nothing meaningful to divide by.
+
+Install to Trial sits downstream of several steps. If it drops, compare it against Paywall Rate and Paywall Conversion to find where the funnel changed.

content/docs/dashboard/charts/meta.json

@@ -13,6 +13,7 @@
         "---Subscriptions---",
         "active-subscriptions",
         "paid-conversion",
+        "install-to-trial",
         "new-trials",
         "trial-conversion",
         "new-subscriptions",
@@ -37,6 +38,7 @@
         "cpm",
         "cpt",
         "cpp",
-        "blended-cpt"
+        "blended-cpt",
+        "blended-cpi"
     ]
 }

content/docs/dashboard/guides/acquisition-cohort-report.mdx

@@ -0,0 +1,47 @@
+---
+title: "Acquisition Cohort Report"
+description: "Pull installs, trials, ad spend, CPI, and install-cohorted revenue per campaign, ad set, ad, or country through the Superwall MCP or API."
+---
+The acquisition cohort report answers a single question: for the users acquired through a given campaign, ad set, ad, or country, what did they cost and what have they earned back so far?
+
+It is available through the [Superwall MCP](/dashboard/guides/superwall-mcp), where you can ask your agent for something like "show me installs and D30 revenue by campaign for the last 30 days", and over the API at `POST /v2/charts/acquisition-cohort-report`.
+
+## What it returns
+
+Each row is one value of the dimension you grouped by, plus a row for the organic/unattributed bucket. For every row you get:
+
+| Column | Meaning |
+| --- | --- |
+| `installs` | Installs in the window. For campaign, ad set, and ad, these come from MMP install matching; for country, from the SDK's install geo. |
+| `trials` | Trial starts, cohorted by install date. |
+| `install_to_trial_rate` | `trials ÷ installs`. |
+| `spend` | Ad-network spend. Campaign dimension only. |
+| `cpi` | Cost per install: `spend ÷ installs`. Campaign dimension only. |
+| `revenue` | Net proceeds per requested window, keyed by window (`d4`, `d14`, `d30`, and so on). |
+
+Revenue is **cohorted by install date**, not by purchase date: the `d30` figure for a campaign is what the users it acquired had earned you within 30 days of installing, however long ago that was.
+
+## Choosing your windows
+
+By default the report returns `d4`, `d14`, and `d30`. You can request any combination of `d1`, `d3`, `d4`, `d7`, `d14`, `d30`, and `d90`.
+
+Shorter windows tell you sooner whether a campaign is working; longer windows tell you more accurately. A campaign that looks weak at `d4` may look very different at `d30`.
+
+## Reading zero versus null
+
+The report distinguishes "we measured nothing" from "we could not measure":
+
+- **0** means the source was available and genuinely saw nothing. A campaign with `installs: 0` is one the MMP has no matched installs for, even though it has revenue attributed to it.
+- **null** means the source itself was unavailable, or a rate or cost had nothing to divide by. On the campaign, ad set, and ad dimensions, `installs` is null when the report is not scoped to production only, because MMP installs are production-only. The country dimension counts installs from SDK data instead, so it keeps its install column on any environment filter. `spend` and `cpi` are null on every dimension except campaign, and null on all rows when the window contains no spend at all, so a report never claims your installs were free just because no ad account is connected.
+
+## Totals are blended
+
+`totals.cpi` and `totals.install_to_trial_rate` divide by **all** installs in the window, organic included. They are blended figures and deliberately are not the sum of the per-row values: a paid campaign's own CPI is typically higher than the blended CPI, because the blend is spreading the same spend across organic installs too.
+
+## Things worth knowing
+
+Ad spend has campaign granularity only. It carries no ad set id, ad id, or country, which is why `spend` and `cpi` appear on the campaign dimension and nowhere else, and why they need a connected ad account. See [Meta Ads](/integrations/meta-ads).
+
+On ad dimensions, installs are windowed by MMP match time while trials and revenue are cohorted by SDK install date. At the edges of a window those two can disagree slightly, which occasionally pushes `install_to_trial_rate` above 1.
+
+The report defaults to production only. Widening the environment filter to include sandbox makes the revenue side describe a different population than MMP installs can, so on the campaign, ad set, and ad dimensions the install column drops to null rather than comparing two different things. The country dimension is unaffected: its installs come from SDK data and follow the same environment filter as revenue.

content/docs/dashboard/guides/superwall-mcp.mdx

@@ -57,15 +57,16 @@ When you add the MCP via a CLI tool (Claude Code, Codex, or Cursor), a browser w
 
 The Superwall MCP can manage nearly everything you'd normally do in the dashboard:
 
-- **Organizations** — list your organizations or create new ones.
-- **Projects** — create, update, archive, and unarchive projects.
-- **Applications** — add iOS, Android, or web apps to a project.
-- **Entitlements** — create, update, list, and delete entitlements that define what features users unlock.
-- **Products** — create and manage products linked to App Store Connect or Google Play, with subscription details and pricing.
-- **Templates** — browse available paywall templates to use as a starting point.
-- **Paywalls** — create paywalls from templates or from scratch, attach products, set presentation style and feature gating, and archive or unarchive them.
-- **Campaigns** — set up simple campaigns that show a paywall to 100% of users, or create advanced campaigns with A/B testing, holdout groups, and automatic optimization.
-- **Webhooks** — create and manage webhook endpoints, inspect event deliveries, rotate secrets, and retry failed deliveries.
+- **Organizations**: list your organizations or create new ones.
+- **Projects**: create, update, archive, and unarchive projects.
+- **Applications**: add iOS, Android, or web apps to a project.
+- **Entitlements**: create, update, list, and delete entitlements that define what features users unlock.
+- **Products**: create and manage products linked to App Store Connect or Google Play, with subscription details and pricing.
+- **Templates**: browse available paywall templates to use as a starting point.
+- **Paywalls**: create paywalls from templates or from scratch, attach products, set presentation style and feature gating, and archive or unarchive them.
+- **Campaigns**: set up simple campaigns that show a paywall to 100% of users, or create advanced campaigns with A/B testing, holdout groups, and automatic optimization.
+- **Webhooks**: create and manage webhook endpoints, inspect event deliveries, rotate secrets, and retry failed deliveries.
+- **Analytics**: pull chart data, and run the [acquisition cohort report](/dashboard/guides/acquisition-cohort-report) to see installs and install-cohorted revenue per campaign, ad set, ad, or country.
 
 It does not directly control the live paywall editor canvas. For live design edits, use [AI Chat Builder](/dashboard/dashboard-creating-paywalls/paywall-editor-ai-chat) inside the editor or connect an external agent with [Editor MCP](/dashboard/dashboard-creating-paywalls/paywall-editor-mcp).
 

content/docs/dashboard/meta.json

@@ -31,6 +31,7 @@
         "guides/superwall-skill",
         "guides/superwall-cli",
         "guides/superwall-mcp",
+        "guides/acquisition-cohort-report",
         "guides/migrating-from-revenuecat-to-superwall",
         "guides/pre-launch-checklist",
         "guides/using-superwall-for-onboarding-flows",

content/docs/integrations/meta-ads.mdx

@@ -78,6 +78,12 @@ Superwall sends these events to your dataset. All six are on by default; leave t
 
 Events are sent for every user, not just users attributed to your ads. Meta uses them for delivery optimization and its own attribution.
 
+When **Subscription Start** is enabled, a free trial converting to paid also sends `sw_subscription_start`, carrying the purchase's `value` and `currency` plus `is_trial_conversion: true` in `custom_data`, so Meta sees revenue at the moment a trial starts paying, not just the trial start. Direct paid signups and trial conversions share one event on purpose: Meta's delivery optimizes per event, and pooling both keeps its volume high. Ordinary renewals (rebills) are never sent.
+
+If you connected Meta before trial-conversion forwarding shipped, it activates the next time you click **Save changes** on this page.
+
+To improve [Event Match Quality](https://www.facebook.com/business/help/765081237991954), Superwall includes a hashed country whenever one is available. Free Trial Start, Subscription Start, and One-Time Purchase use the store transaction's country. For the paywall and transaction events, setting the `country` user attribute (a two-letter code like `US`) takes precedence over the region of the user's matched install. Organic users without the attribute send no country.
+
 Meta requires you to acknowledge new custom events and allow the domain they come from:
 
 <Steps>