OneSignal

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.

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

// After OneSignal initializes and identity is set
if let oneSignalId = OneSignal.User.onesignalId {
    Superwall.shared.setIntegrationAttributes([
        .onesignalId: oneSignalId
    ])
}

Android

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.

Superwall.shared.setUserAttributes([
    "onesignalId": oneSignalId
])

Superwall.instance.setUserAttributes(
    mapOf("onesignalId" to oneSignalId)
)

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.

Subscription Status

The subscription_status tag is designed for segmentation and Journey branching.

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
• OneSignal Update user API
• RevenueCat OneSignal integration