superwall · anglinb · Jun 29, 2026
diff --git a/content/docs/integrations/meta.json b/content/docs/integrations/meta.json
@@ -15,6 +15,7 @@
     "mixpanel",
     "amplitude",
     "customer-io",
+    "onesignal",
     "firebase",
     "statsig",
     "appstack",

diff --git a/content/docs/integrations/onesignal.mdx b/content/docs/integrations/onesignal.mdx
@@ -0,0 +1,162 @@
+---
+title: "OneSignal"
+description: "Sync Superwall subscription state to OneSignal user tags for messaging, segmentation, and Journeys."
+---
+
+In the **Communication** section within **Integrations**, you can connect your OneSignal app to Superwall.
+
+Use this integration when OneSignal is your messaging or lifecycle marketing destination and you want subscription state available as OneSignal user tags.
+
+## Features
+
+- **Subscription state tags**: Updates OneSignal users with the latest Superwall subscription status.
+- **Messaging segmentation**: Use tags such as `subscription_status`, `active_subscription`, and `product_id` in OneSignal segments and Journeys.
+- **Lifecycle context**: Includes store, environment, purchase, expiration, transaction, project, and application details.
+- **Sandbox controls**: Sends sandbox events to a sandbox OneSignal app when configured, or skips them when sandbox credentials are blank.
+- **Typed SDK attributes**: iOS and Android SDKs expose typed OneSignal integration attributes for the OneSignal User ID.
+
+## Configuration
+
+OneSignal requires an App ID and REST API key to update users through the OneSignal User API. Configure production credentials, and optionally configure sandbox credentials if you want sandbox subscription events to update a separate OneSignal app.
+
+| Field | Description |
+| ----- | ----------- |
+| OneSignal App ID | Your production OneSignal app ID. |
+| REST API key | Your production OneSignal REST API key. |
+| Sandbox OneSignal App ID | Optional. Used for sandbox events. If blank, sandbox events are skipped. |
+| Sandbox REST API key | Optional. Used for sandbox events. If blank, sandbox events are skipped. |
+| Test OneSignal User ID | Optional. Used only by the dashboard validation action to update a known test user. |
+
+## SDK Setup
+
+Superwall updates OneSignal users after subscription events happen. To match those events to the correct OneSignal user, pass the OneSignal User ID to Superwall as soon as OneSignal makes it available.
+
+If your app uses OneSignal external IDs, call `OneSignal.login(...)` before reading the OneSignal User ID.
+
+### iOS
+
+```swift
+// After OneSignal initializes and identity is set
+if let oneSignalId = OneSignal.User.onesignalId {
+    Superwall.shared.setIntegrationAttributes([
+        .onesignalId: oneSignalId
+    ])
+}
+```
+
+### Android
+
+```kotlin
+import com.superwall.sdk.models.attribution.AttributionProvider
+
+// After OneSignal initializes and identity is set
+OneSignal.User.onesignalId?.let { oneSignalId ->
+    Superwall.instance.setIntegrationAttributes(
+        mapOf(AttributionProvider.ONESIGNAL_ID to oneSignalId)
+    )
+}
+```
+
+### Other SDKs
+
+If your Superwall SDK does not yet expose a typed OneSignal integration attribute, set `onesignalId` as a user attribute instead.
+
+```swift
+Superwall.shared.setUserAttributes([
+    "onesignalId": oneSignalId
+])
+```
+
+```kotlin
+Superwall.instance.setUserAttributes(
+    mapOf("onesignalId" to oneSignalId)
+)
+```
+
+```dart
+await Superwall.shared.setUserAttributes({
+  'onesignalId': oneSignalId,
+});
+```
+
+Superwall also accepts `$onesignalUserId`, `$onesignalId`, `oneSignalUserId`, and `onesignalUserId` as raw user-attribute aliases, but `onesignalId` is the recommended key.
+
+## Tags
+
+Superwall updates OneSignal user tags through the OneSignal User API.
+
+| Tag | Description |
+| --- | ----------- |
+| `app_user_id` | Your app's user identifier from the Superwall event. |
+| `period_type` | Subscription period type, such as `trial`, `intro`, or `normal`. |
+| `purchased_at` | Purchase time as an ISO timestamp. |
+| `expiration_at` | Expiration time as an ISO timestamp, when available. |
+| `store` | Store that produced the event, such as `app_store`, `play_store`, or `stripe`. |
+| `environment` | `production` or `sandbox`. |
+| `last_event_type` | Original Superwall event name. |
+| `superwall_event_type` | Normalized Superwall event type, such as `sw_subscription_start`. |
+| `product_id` | Product identifier from the purchase. |
+| `transaction_id` | Transaction identifier for the event. |
+| `original_transaction_id` | Store original transaction identifier, when available. |
+| `subscription_status` | Current status inferred from the latest event. |
+| `active_subscription` | `true` when the latest event represents active access. |
+| `superwall_project_id` | Superwall project ID. |
+| `superwall_application_id` | Superwall application ID, when available. |
+
+## Subscription Status
+
+The `subscription_status` tag is designed for segmentation and Journey branching.
+
+| Status | When it is set |
+| ------ | -------------- |
+| `trial` | Trial started or trial uncancelled. |
+| `intro_offer` | Intro offer started or intro offer uncancelled. |
+| `active` | Subscription start, renewal, uncancellation, product change, trial conversion, intro offer conversion, or non-renewing purchase. |
+| `cancelled` | Trial, intro offer, or regular subscription cancellation. |
+| `billing_issue` | Billing issue event. |
+| `paused` | Subscription paused event. |
+| `expired` | Trial, intro offer, or regular subscription expiration. |
+| `refunded` | Refund event. |
+| `test` | Test event. |
+| `unknown` | Events that cannot be mapped to a subscription state. |
+
+`active_subscription` is `true` for `active`, `trial`, `intro_offer`, `cancelled`, and `billing_issue` statuses. A cancelled subscription can remain active until its expiration date, so it is still treated as active access.
+
+## Sandbox Handling
+
+Sandbox events use the sandbox OneSignal App ID and REST API key. If either sandbox value is missing, Superwall skips sandbox events instead of sending them to your production OneSignal app.
+
+Production events always use the production OneSignal App ID and REST API key.
+
+## Validation
+
+The dashboard validation action requires a test OneSignal User ID. Validation sends a Superwall test event to that user and updates the same tags the integration uses for real events.
+
+If you do not configure a test OneSignal User ID, validation fails without sending a request. Real subscription events can still be sent when they include `onesignalId`.
+
+## Troubleshooting
+
+### Tags are not updating in OneSignal
+
+1. Confirm the production OneSignal App ID and REST API key are configured.
+2. Confirm your app sends `onesignalId` to Superwall before subscription events occur.
+3. Confirm the value is the OneSignal User ID, not an external ID or push subscription ID.
+4. Confirm the user exists in the OneSignal app configured in Superwall.
+
+### Sandbox events are skipped
+
+1. Confirm both sandbox fields are configured.
+2. Confirm the sandbox REST API key belongs to the sandbox OneSignal app.
+3. Confirm the event environment is `sandbox`.
+
+### Validation fails
+
+1. Add a test OneSignal User ID in the integration settings.
+2. Confirm the test user exists in the selected OneSignal app.
+3. Confirm the REST API key has permission to update users.
+
+## References
+
+- [OneSignal Users and aliases](https://documentation.onesignal.com/docs/en/users)
+- [OneSignal Update user API](https://documentation.onesignal.com/reference/update-user)
+- [RevenueCat OneSignal integration](https://www.revenuecat.com/docs/integrations/third-party-integrations/onesignal)