Skip to content

docs(integrations): correct emitted event names across integration pages #255

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Makisuo wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(integrations): correct emitted event names across integration pages #255

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 68 additions & 35 deletions content/docs/integrations/amplitude.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,37 +59,70 @@ Fill out the following fields and **click** the **Enable Amplitude** button at t

### Event mapping

Superwall events are transformed into human-readable Amplitude events:
Superwall events are transformed into readable, Title Case Amplitude events.

#### Event name format
All events are prefixed with `[Superwall]` followed by a descriptive name:
All events are prefixed with `[Superwall] ` followed by the Title Case name:
- Example: `[Superwall] Trial Start`
- Example: `[Superwall] Subscription Renewal`

#### Complete event mapping

| Superwall Event | Amplitude Event | Description |
|-----------------|-----------------|-------------|
| `initial_purchase` + TRIAL | `[Superwall] Trial Start` | Trial begins |
| `initial_purchase` + INTRO | `[Superwall] Intro Offer Start` | Intro offer begins |
| `initial_purchase` + NORMAL | `[Superwall] Subscription Start` | Paid subscription begins |
| `renewal` + trial conversion | `[Superwall] Trial Conversion` | Trial converts to paid |
| `renewal` + INTRO | `[Superwall] Intro Offer Conversion` | Intro converts to regular |
| `renewal` + NORMAL | `[Superwall] Subscription Renewal` | Regular renewal |
| `cancellation` + TRIAL | `[Superwall] Trial Cancellation` | Trial cancelled |
| `cancellation` + INTRO | `[Superwall] Intro Offer Cancellation` | Intro cancelled |
| `cancellation` + NORMAL | `[Superwall] Subscription Cancellation` | Subscription cancelled |
| `uncancellation` + TRIAL | `[Superwall] Trial Uncancellation` | Trial reactivated |
| `uncancellation` + INTRO | `[Superwall] Intro Offer Uncancellation` | Intro reactivated |
| `uncancellation` + NORMAL | `[Superwall] Subscription Uncancellation` | Subscription reactivated |
| `expiration` + TRIAL | `[Superwall] Trial Expiration` | Trial ended |
| `expiration` + INTRO | `[Superwall] Intro Offer Expiration` | Intro ended |
| `expiration` + NORMAL | `[Superwall] Subscription Expiration` | Subscription ended |
| `billing_issue` | `[Superwall] Billing Issue` | Payment failed |
| `subscription_paused` | `[Superwall] Subscription Paused` | Subscription paused |
| `product_change` | `[Superwall] Product Change` | Plan changed |
| `non_renewing_purchase` | `[Superwall] Non-Renewing Purchase` | One-time purchase |
| Any with `price < 0` | `[Superwall] Refund` | Refund processed |
- Example: `[Superwall] Renewal`

Each event also has a stable `sw_*` identifier. The identifier is internal and **not** what Amplitude receives — the value in the **Amplitude Event** column is what arrives in your project.

These names are **not configurable**. There is no per-customer event renaming for Amplitude; every project on this integration receives the same Title Case names.

#### Trial events

| Superwall Event | Amplitude Event | Identifier | Description |
|-----------------|-----------------|------------|-------------|
| `initial_purchase` + TRIAL | `[Superwall] Trial Start` | `sw_trial_start` | Trial begins |
| `cancellation` + TRIAL | `[Superwall] Trial Cancelled` | `sw_trial_cancelled` | Trial cancelled |
| `uncancellation` + TRIAL | `[Superwall] Trial Uncancelled` | `sw_trial_uncancelled` | Trial reactivated |
| `expiration` + TRIAL | `[Superwall] Trial Expired` | `sw_trial_expired` | Trial ended |
| `renewal` + `isTrialConversion: true` | `[Superwall] Trial Converted` | `sw_trial_converted` | Trial converts to paid |

#### Intro offer events

| Superwall Event | Amplitude Event | Identifier | Description |
|-----------------|-----------------|------------|-------------|
| `initial_purchase` + INTRO | `[Superwall] Intro Offer Start` | `sw_intro_offer_start` | Intro offer begins |
| `cancellation` + INTRO | `[Superwall] Intro Offer Cancelled` | `sw_intro_offer_cancelled` | Intro offer cancelled |
| `uncancellation` + INTRO | `[Superwall] Intro Offer Uncancelled` | `sw_intro_offer_uncancelled` | Intro offer reactivated |
| `expiration` + INTRO | `[Superwall] Intro Offer Expired` | `sw_intro_offer_expired` | Intro offer ended |
| `renewal` + INTRO | `[Superwall] Intro Offer Converted` | `sw_intro_offer_converted` | Intro converts to regular |

#### Subscription events

| Superwall Event | Amplitude Event | Identifier | Description |
|-----------------|-----------------|------------|-------------|
| `initial_purchase` + NORMAL | `[Superwall] Subscription Start` | `sw_subscription_start` | Paid subscription begins |
| `renewal` + NORMAL | `[Superwall] Renewal` | `sw_renewal` | Regular renewal |
| `cancellation` + NORMAL | `[Superwall] Subscription Cancelled` | `sw_subscription_cancelled` | Subscription cancelled |
| `uncancellation` + NORMAL | `[Superwall] Subscription Uncancelled` | `sw_subscription_uncancelled` | Subscription reactivated |
| `expiration` + NORMAL | `[Superwall] Subscription Expired` | `sw_subscription_expired` | Subscription ended |

#### Other events

Matched on the event name alone, **before** `periodType` is consulted:

| Superwall Event | Amplitude Event | Identifier | Description |
|-----------------|-----------------|------------|-------------|
| `test` | `[Superwall] Test Event` | `sw_test` | Test event |
| `product_change` | `[Superwall] Product Change` | `sw_product_change` | Plan changed |
| `subscription_paused` | `[Superwall] Subscription Paused` | `sw_subscription_paused` | Subscription paused |
| `non_renewing_purchase` | `[Superwall] Non-Renewing Purchase` | `sw_non_renewing_purchase` | One-time purchase |
| `billing_issue` | `[Superwall] Billing Issue` | `sw_billing_issue` | Payment failed |
| Any with `price < 0` | `[Superwall] Refund` | `sw_refund` | Refund processed |

#### Matching order

Events are matched in this order — which is why a `billing_issue` during a trial arrives as `[Superwall] Billing Issue`, not a trial event:

1. `test`, `product_change`, `subscription_paused`, `non_renewing_purchase`, `billing_issue` — matched on the event name, for any `periodType`.
2. `price < 0` → `Refund`.
3. `periodType` selects the Trial / Intro / Subscription table.
4. Unmatched names within a known `periodType` → `Unknown` (`sw_unknown`).

A `renewal` during a trial without `isTrialConversion` is a plain `[Superwall] Renewal`. There is no transfer event, so subscription transfers fall through to `Unknown`.

### Event properties

Expand All @@ -108,7 +141,7 @@ Every Amplitude event includes comprehensive properties:
- `price`: Same as revenue
- `quantity`: Always 1
- `productId`: Product identifier
- `revenueType`: Same as event type (for revenue categorization)
- `revenueType`: The event name **without** the `[Superwall] ` prefix (for revenue categorization)

#### Event properties object
All Superwall webhook data fields are included:
Expand Down Expand Up @@ -149,7 +182,7 @@ The `sales_reporting` setting determines which value is used:
"revenue": 9.99,
"price": 9.99,
"productId": "com.example.premium",
"revenueType": "[Superwall] Subscription Start"
"revenueType": "Subscription Start"
}
```

Expand All @@ -160,7 +193,7 @@ The `sales_reporting` setting determines which value is used:
"revenue": -9.99,
"price": -9.99,
"productId": "com.example.premium",
"revenueType": "[Superwall] Refund"
"revenueType": "Refund"
}
```

Expand Down Expand Up @@ -258,21 +291,21 @@ Check your Amplitude project:

#### Revenue analytics
```
Events: [Superwall] Subscription Start, [Superwall] Subscription Renewal
Events: [Superwall] Subscription Start, [Superwall] Renewal
Metric: Sum of revenue
Segment by: platform, productId, countryCode
```

#### Conversion funnel
```
1. [Superwall] Trial Start
2. [Superwall] Trial Conversion
2. [Superwall] Trial Converted
Conversion Rate: Step 2 / Step 1
```

#### Churn analysis
```
Events: [Superwall] Subscription Cancellation
Events: [Superwall] Subscription Cancelled
Segment by: cancelReason, periodType, price tier
```

Expand Down Expand Up @@ -302,7 +335,7 @@ Calculate: Sum of revenue per user
#### Duplicate events

The integration uses `insert_id` to prevent duplicates:
- Format: `sw_eventId-eventName`
- Format: `sw_` + the Superwall event id with its first colon replaced by a dash
- Amplitude automatically deduplicates by `insert_id`

#### User attribution issues
Expand Down
55 changes: 24 additions & 31 deletions content/docs/integrations/customer-io.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,6 @@ In the **Communication** section within **Integrations**, you can connect your C
|-------|-------------|---------|
| `sandbox_api_key` | Separate Pipelines API key for sandbox/test events | None (sandbox events skipped) |
| `anonymous_user_behavior` | How to handle events from users without an app user ID | `"send"` |
| `eventNameMappings` | Custom mapping to rename default event names | None |

### Example Configuration

Expand All @@ -45,12 +44,7 @@ In the **Communication** section within **Integrations**, you can connect your C
"api_key": "your-pipelines-api-key",
"sales_reporting": "Revenue",
"sandbox_api_key": "your-sandbox-pipelines-api-key",
"anonymous_user_behavior": "send",
"eventNameMappings": {
"sw_trial_start": "trial_started",
"sw_subscription_start": "subscription_started",
"sw_renewal": "subscription_renewed"
}
"anonymous_user_behavior": "send"
}
```

Expand All @@ -69,7 +63,9 @@ The Customer.io integration uses the **Pipelines API** (part of Customer.io Data

## Event Mapping

Superwall subscription events are transformed into Customer.io events based on the event type and subscription period. All events are prefixed with `sw_` by default.
Superwall subscription events are transformed into Customer.io events based on the event type and subscription period. Customer.io receives the `sw_*` identifier itself — unlike Mixpanel, Amplitude and Statsig, which receive a Title Case name and keep `sw_*` internal.

These names are **not configurable**. There is no per-customer event renaming for Customer.io; every workspace on this integration receives the same `sw_*` names.

### Trial Events

Expand Down Expand Up @@ -104,14 +100,28 @@ Superwall subscription events are transformed into Customer.io events based on t

### Other Events

Matched on the event name alone, **before** `periodType` is consulted:

| Superwall Event | Customer.io Event |
|-----------------|-------------------|
| `TEST` | `sw_test` |
| `PRODUCT_CHANGE` | `sw_product_change` |
| `BILLING_ISSUE` | `sw_billing_issue` |
| `SUBSCRIPTION_PAUSED` | `sw_subscription_paused` |
| `NON_RENEWING_PURCHASE` | `sw_non_renewing_purchase` |
| `BILLING_ISSUE` | `sw_billing_issue` |
| Any event with `price < 0` | `sw_refund` |

### Matching Order

Events are matched in this order — which is why a `BILLING_ISSUE` during a trial arrives as `sw_billing_issue`, not a trial event:

1. `TEST`, `PRODUCT_CHANGE`, `SUBSCRIPTION_PAUSED`, `NON_RENEWING_PURCHASE`, `BILLING_ISSUE` — matched on the event name, for any `periodType`.
2. `price < 0` → `sw_refund`.
3. `periodType` selects the Trial / Intro / Subscription table.
4. Unmatched names within a known `periodType` → `sw_unknown`.

There is no transfer event, so subscription transfers fall through to `sw_unknown`.

## Event Properties

Each event sent to Customer.io includes comprehensive properties from the original Superwall event, plus additional formatted fields for revenue tracking.
Expand Down Expand Up @@ -224,23 +234,6 @@ Customer.io offers data residency in two regions. The integration automatically

Choose the region that matches your Customer.io workspace configuration. Using the wrong region will result in authentication errors.

## Custom Event Names

Use `eventNameMappings` to rename default event names to match your existing Customer.io conventions:

```json
{
"eventNameMappings": {
"sw_trial_start": "Started Free Trial",
"sw_subscription_start": "Subscribed",
"sw_renewal": "Subscription Renewed",
"sw_subscription_cancelled": "Subscription Cancelled",
"sw_refund": "Refund Processed"
}
}
```

Only events you specify in the mapping are renamed. All other events keep their default `sw_` prefixed names.

## Testing the Integration

Expand Down Expand Up @@ -275,7 +268,7 @@ Verify these scenarios work correctly:

3. **Handle anonymous users thoughtfully**: If your app requires login, use `"dontSend"` to avoid cluttering Customer.io with unidentifiable users.

4. **Keep event names consistent**: If you have existing events in Customer.io, use `eventNameMappings` to maintain naming consistency across your data.
4. **Map names on your side**: Superwall always sends the `sw_*` names above. If you need different naming in Customer.io, transform them downstream in your Data Pipelines source.

5. **Verify your region**: Ensure your `region` setting matches your Customer.io workspace location to avoid authentication failures.

Expand Down Expand Up @@ -343,13 +336,13 @@ Build comprehensive revenue reporting:

**Solution:** Revenue properties (`price`, `currency`, `product_id`, `subscription_id`) are only added when the price is non-zero. This is expected behavior.

### Wrong Event Names
### Unexpected Event Names

**Possible causes:**
- Event name mappings not configured
- Typo in mapping configuration
- Expecting custom names — Superwall always sends the fixed `sw_*` names listed above
- The event resolved differently than expected (see [Matching Order](#matching-order))

**Solution:** Check your `eventNameMappings` configuration. Keys should be the default event names (e.g., `sw_trial_start`), and values should be your desired custom names.
**Solution:** Compare the received name against the mapping tables above. A `BILLING_ISSUE` during a trial, for example, arrives as `sw_billing_issue` rather than a trial event.

## Rate Limits

Expand Down
Loading
Loading