---
title: "OneSignal"
description: "OneSignal as a planned MainSDK notify driver for push - what to set up, main.yaml, testing and swapping."
section: "integrations"
canonical: "https://mainsdk.dev/docs/integrations/onesignal"
updated: "2026-10-28"
---

# OneSignal

> OneSignal as a planned MainSDK notify driver for push - what to set up, main.yaml, testing and swapping.

Canonical: https://mainsdk.dev/docs/integrations/onesignal · Updated: 2026-10-28

OneSignal is a hosted service for push notifications and other messaging channels. It is named as a [`notify`](https://mainsdk.dev/docs/interfaces/notify) driver in the MainSDK requirements, so a person reached on push could get it through OneSignal. Pick it if your team already manages push audiences in OneSignal.

## Interfaces it serves

### Notifications (`notify`)

- Status: Building for 0.3 · ships as a stable API
- Driver: `onesignal` (OneSignal, planned driver)
- Docs: https://mainsdk.dev/docs/interfaces/notify.md

```yaml
notify:
  driver: onesignal
```

Swap to another provider: `whatsapp-cloud`, `bird`, `msg91`, `twilio`, `local`, `fcm`, `apns`, `expo`, `resend`, `ses`, `slack`, `pagerduty`, `opsgenie`, `webhook`.

## Before you start

1. Create a OneSignal app and connect your push credentials (FCM for Android, an APNs key for iOS).
2. Create an API key for server-side sends.

Store the API key in your secrets manager.

## Configure

```yaml title="main.yaml"
notify:
  channels: [push, whatsapp, sms, email]
  # push through OneSignal: [TBD] the push block shape for this driver is not in the spec yet
```

Its credential will be a `secret:` reference such as `secret:ONESIGNAL_API_KEY` (suggested name).

## Use it

```ts title="app/orders/ship.ts"
import { notify } from "mainsdk";

await notify(user, { template: "order.shipped", data: { orderId: order.id }, category: "orders" });
```

## Local development and testing

`createTestApp()` from `@mainsdk/testing` runs `notify` on its in-memory fake, and `chaos.on("notify", { outage: true })` simulates an outage. Until a push driver is configured, the push channel is skipped.

## What MainSDK adds on top

- Push only with opt-in, respecting opt-outs and quiet hours.
- No personal data in push payloads.
- A retry never sends twice.

See [Notifications](https://mainsdk.dev/docs/interfaces/notify).

## Limits and notes

- Planned driver, not in the spec yet. The email-notify spec lists OneSignal for the driver kit, later.
- Push through FCM, APNs and Expo comes with the expo-adapter spec (phase 3).

## Swap to or from it

```yaml title="main.yaml"
notify:
  push: { drivers: [fcm, apns], via: expo }   # instead of OneSignal
```

> **Warning:** OneSignal keeps its own subscriptions for each device. Moving to another push driver needs devices to register again; how MainSDK runs that move is [TBD].

## FAQ

**Can I use OneSignal today?** Not through MainSDK yet. Use the FCM, APNs or Expo drivers when push arrives in phase 3.

**Do OneSignal segments replace notify preferences?** No. `notify` decides who gets a message from each person's preferences and consent.

## Next

- [Notifications](https://mainsdk.dev/docs/interfaces/notify)
- [Expo](https://mainsdk.dev/docs/integrations/expo), [Firebase Cloud Messaging](https://mainsdk.dev/docs/integrations/firebase-cloud-messaging) and [Apple Push Notification service](https://mainsdk.dev/docs/integrations/apns)