From 29136f4491a37f91695cf3c34520769090ccd211 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 27 Jun 2026 14:00:33 +0000 Subject: [PATCH 1/2] docs: introduce track() as analytics-only alias of register Adds a section to the Showing Paywalls overview explaining the new fire-and-forget track() method: a thin alias of register/registerPlacement with no paywall handler and no feature closure, for sending Superwall every analytics event uncapped and free and querying it back via the Query API. Clarifies when to use track (pure analytics) vs register (gate a feature or present a paywall). Augments existing register/paywall content; nothing removed. --- .../showing-paywalls/feature-gating.mdx | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/content/shared/showing-paywalls/feature-gating.mdx b/content/shared/showing-paywalls/feature-gating.mdx index 31a318e8..818a3ce7 100644 --- a/content/shared/showing-paywalls/feature-gating.mdx +++ b/content/shared/showing-paywalls/feature-gating.mdx @@ -344,6 +344,45 @@ Analytics.shared.track( ``` ::: +### Tracking analytics events with `track` + +If all you want to do is send Superwall an analytics event — with no paywall, no feature gate, and no callback — use `track`. It's a fire-and-forget alias of `register`/`registerPlacement` that drops the presentation handler and feature closure entirely: + +:::ios + + +```swift Swift +Superwall.shared.track("workout_complete", params: ["total_workouts": 17]) +``` + +::: +:::android +```kotlin Kotlin +Superwall.instance.track(event = "workout_complete", params = mapOf("total_workouts" to 17)) +``` +::: +:::flutter +```dart Flutter +Superwall.shared.track("workout_complete", params: {"total_workouts": 17}); +``` +::: +:::expo +```tsx React Native +Superwall.shared.track("workout_complete", { total_workouts: 17 }); +``` +::: + +Because there's no handler or feature block to fill in, `track` is the simplest way to pipe **every** analytics event you already fire into Superwall. There's no per-event fee and no cap — send us everything, then query it back with row-level-security-protected SQL through the [Query API](/dashboard/guides/query-clickhouse). That makes Superwall a viable, agent-first home for your product analytics alongside (or instead of) Mixpanel, Amplitude, and PostHog — on top of everything it already does for paywalls. + +#### `track` vs. `register` + +Both methods record the same placement and parameters, so anything you `track` can later become a paywall moment without an app update. The only difference is intent: + +- Reach for **`register`** (or **`registerPlacement`**) when the event should be able to **gate a feature or present a paywall** — you pass a `feature:` closure (and optionally a presentation handler) that runs based on the user's entitlements. +- Reach for **`track`** when you just want a **pure analytics event** with no paywall behavior and nothing to run afterward. + +So if you find yourself calling `register` with an empty feature block purely to log an event, reach for `track` instead. + ### Getting a presentation result Use `getPresentationResult(forPlacement:params:)` when you need to ask the SDK what would happen when registering a placement — without actually showing a paywall. Superwall evaluates the placement and its audience filters then returns a `PresentationResult`. You can use this to adapt your app's behavior based on the outcome (such as showing a lock icon next to a pro feature if they aren't subscribed). From c613dcbef53316e862b322e16d2c6126d14e540a Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 28 Jun 2026 19:32:45 +0000 Subject: [PATCH 2/2] Reframe analytics docs around register instead of a track alias --- .../showing-paywalls/feature-gating.mdx | 28 +++++++++---------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/content/shared/showing-paywalls/feature-gating.mdx b/content/shared/showing-paywalls/feature-gating.mdx index 818a3ce7..c16e5c7e 100644 --- a/content/shared/showing-paywalls/feature-gating.mdx +++ b/content/shared/showing-paywalls/feature-gating.mdx @@ -344,44 +344,42 @@ Analytics.shared.track( ``` ::: -### Tracking analytics events with `track` +### Every `register` call is an analytics event -If all you want to do is send Superwall an analytics event — with no paywall, no feature gate, and no callback — use `track`. It's a fire-and-forget alias of `register`/`registerPlacement` that drops the presentation handler and feature closure entirely: +Registering a placement doesn't only decide whether to show a paywall — it also records an analytics event. Every `register` call is captured by Superwall, **uncapped and free**, so you can use the SDK you already have as a full-fledged analytics destination with no separate library to install. + +You don't need a feature closure or a presentation handler to log an event. Call `register` with just a placement name (and, optionally, params) and Superwall records it — fire-and-forget: :::ios ```swift Swift -Superwall.shared.track("workout_complete", params: ["total_workouts": 17]) +Superwall.shared.register(placement: "workout_complete", params: ["total_workouts": 17]) ``` ::: :::android ```kotlin Kotlin -Superwall.instance.track(event = "workout_complete", params = mapOf("total_workouts" to 17)) +Superwall.instance.register("workout_complete", params = mapOf("total_workouts" to 17)) ``` ::: :::flutter ```dart Flutter -Superwall.shared.track("workout_complete", params: {"total_workouts": 17}); +Superwall.shared.registerPlacement("workout_complete", params: {"total_workouts": 17}); ``` ::: :::expo ```tsx React Native -Superwall.shared.track("workout_complete", { total_workouts: 17 }); +Superwall.shared.register({ + placement: "workout_complete", + params: new Map([["total_workouts", 17]]), +}); ``` ::: -Because there's no handler or feature block to fill in, `track` is the simplest way to pipe **every** analytics event you already fire into Superwall. There's no per-event fee and no cap — send us everything, then query it back with row-level-security-protected SQL through the [Query API](/dashboard/guides/query-clickhouse). That makes Superwall a viable, agent-first home for your product analytics alongside (or instead of) Mixpanel, Amplitude, and PostHog — on top of everything it already does for paywalls. - -#### `track` vs. `register` - -Both methods record the same placement and parameters, so anything you `track` can later become a paywall moment without an app update. The only difference is intent: - -- Reach for **`register`** (or **`registerPlacement`**) when the event should be able to **gate a feature or present a paywall** — you pass a `feature:` closure (and optionally a presentation handler) that runs based on the user's entitlements. -- Reach for **`track`** when you just want a **pure analytics event** with no paywall behavior and nothing to run afterward. +The exact same call powers both behaviors — the only thing that changes is whether you pass a feature closure or handler. With a `feature:` block, `register` can gate a feature or present a paywall based on the user's entitlements. Without one, it's a pure analytics event with nothing to run afterward. That means anything you log today can become a paywall moment later, **without an app update**. -So if you find yourself calling `register` with an empty feature block purely to log an event, reach for `track` instead. +Because there's no per-event fee and no cap, you can pipe **every** analytics event you already fire into Superwall and then query it back with row-level-security-protected SQL through the [Query API](/dashboard/guides/query-clickhouse). That makes Superwall a viable, agent-first home for your product analytics alongside (or instead of) Mixpanel, Amplitude, and PostHog — on top of everything it already does for paywalls. ### Getting a presentation result