OneSignal

OneSignal is a multi-channel messaging platform for push notifications, in-app messages, email, and SMS, popular for high-volume consumer apps and web.

⚠️

This integration is currently in alpha. Configuration and behaviour may change.

Prerequisites

Complete these steps in OneSignal before configuring Signal.

Access your OneSignal dashboard

Find your App ID

Navigate to Settings > Keys & IDs for your app. Copy the OneSignal App ID (UUID format).

Create a REST API Key

On the same Keys & IDs page, copy the REST API Key. Treat this as a secret — it grants full server-side access to your app.

⚠️

The REST API Key is distinct from the (public) App ID. Never expose the REST API Key in browser code.

Configuration

Field	Type	Required	Description
`app_id`	string	Yes	Your OneSignal App ID (UUID).
`rest_api_key`	secret	Yes	OneSignal REST API Key. Found in Settings > Keys & IDs.

Signal Setup

Quick Setup

Navigate to Integrations in the sidebar.
Open the Integration Library tab.
Find OneSignal under the Marketing Automation category.
Click Install, and fill in the required fields.
Click Install Integration.

API Setup

curl -X POST http://localhost:8084/v1/admin/integration-catalog/onesignal/install \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OneSignal",
    "variant": "default",
    "config": {
      "app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "rest_api_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "delivery_mode": "server_side"
  }'

Event Mapping

Datafly Event	OneSignal Concept	Notes
`page`	User property update	Recent page URL/title written to user properties.
`Product Viewed`	User property update + tag	Recent product ID set as a tag for segment targeting.
`Order Completed`	Outcome event with revenue	Sent via the Outcomes API with `weight` set to revenue.
`identify`	External ID assignment	Sets the user’s `external_id` and updates tags/properties.

Identity

OneSignal uses an External User ID to link subscriptions across browsers and devices.

Field	Source	Notes
`external_id`	`user_id` from `datafly.identify()`	Stable customer ID. All channels (push, email, SMS) for the user are aliased to this.
`email` (alias)	`traits.email`	Used to add an email subscription to the user.
`phone_number` (alias)	`traits.phone`	E.164 format. Used to add an SMS subscription.
`tags`	selected `traits.` and `properties.`	Mapped to OneSignal tags for segmentation.

Call datafly.identify() when the user logs in or signs up:

datafly.identify("user-123", {
  email: "jane@example.com",
  phone: "+447700900123"
});

OneSignal events should be sent under the marketing consent category. OneSignal manages its own per-subscription opt-in records — Signal forwards CMP consent state so server-side workflows can suppress notifications for visitors who declined.

Verify it’s working

Trigger a test event from your website.
In OneSignal, navigate to Audience > Users and look up the test user by external ID or email.
View the user’s Activity and Tags to confirm Signal-delivered updates.
In Signal, check Live Events to confirm delivery with a 200 response status.

Troubleshooting

Symptom	Possible Cause	Resolution
`401 Unauthorized`	Invalid REST API key	Regenerate or verify the key in Settings > Keys & IDs.
User not found	`external_id` mismatch	OneSignal creates a new alias on first sight; check the external_id matches between identify and subsequent calls.
Tags not updating	Tag name conflict	OneSignal tags are case-sensitive. Confirm the tag name matches existing segment rules.
Outcomes not appearing in reports	Outcome name not registered	Create the outcome in Settings > Outcomes before sending events.

Visit OneSignal REST API documentation for full reference.