Skip to main content

Documentation Index

Fetch the complete documentation index at: https://setup.despia.com/llms.txt

Use this file to discover all available pages before exploring further.

Send targeted push notifications to specific users even when your app is closed. Despia includes the native OneSignal SDK at runtime. You link your users to their devices with two function calls, then send notifications from your backend using OneSignal’s REST API.
OneSignal is moving away from Player IDs toward external_id, your own user ID from your database. Despia supports this. Pass your logged-in user’s ID via setonesignalplayerid:// and use include_external_user_ids when sending from your backend.

​
Installation

npm install despia-native

import despia from 'despia-native';

​
How it works

Despia registers the device with OneSignal automatically when the app launches. You link that device to your user by calling setonesignalplayerid:// with your user’s ID on every authenticated app load. OneSignal stores the mapping. When you want to send a notification, your backend calls OneSignal’s REST API with include_external_user_ids targeting that user ID. 
const isDespia = navigator.userAgent.toLowerCase().includes('despia')

// Call on every authenticated load
if (isDespia) {
    despia(`setonesignalplayerid://?user_id=${userId}`)
}
You can check whether the user has push notifications enabled and prompt them to turn it on if not: 
const result = await despia('checkNativePushPermissions://', ['nativePushEnabled'])

if (!result.nativePushEnabled) {
    // User has denied or not yet granted permission
    // Link them to their device settings to enable it
    despia('settingsapp://')
}

// Backend: send a notification to a specific user
const response = await fetch('https://onesignal.com/api/v1/notifications', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Basic YOUR_REST_API_KEY',
    },
    body: JSON.stringify({
        app_id:                     'YOUR_ONESIGNAL_APP_ID',
        include_external_user_ids:  [userId],
        headings:                   { en: 'Title' },
        contents:                   { en: 'Message body' },
    }),
})

Setup Guide

OneSignal dashboard setup, Apple Push Key, Firebase config, and full API reference

Offline Push

Send local notifications without a server using sendlocalpushmsg://

​
OneSignal and Despia setup

Configure OneSignal with your iOS and Android credentials, then connect everything to Despia. The steps go in order, each one feeds the next.
1

Create a OneSignal account

Go to onesignal.com and sign up, or sign in with an existing account. Create a new app or organization. OneSignal is free up to 10,000 subscribers & unlimited push notifications, after which paid plans apply, so account creation does not block early development.
2

Choose Native iOS and Native Android

When OneSignal prompts you to choose platforms, select Native iOS and Native Android. Despia apps are native applications, not web apps, so do not pick the Web Push option even though your app code is web.
3

Generate an Apple Push Key

In Apple Developer Console, go to Certificates, Identifiers & Profiles > Keys > + New. Name the key something like Push Notifications, check Apple Push Notifications service (APNs), and click Continue then Register. Download the .p8 file (you can only download it once), and note the Key ID that appears next to it. Also note your Team ID from the top right corner of Apple Developer Console.
4

Add Push Notifications to your core bundle ID

Still in Apple Developer Console, go to Identifiers, click into your core app bundle ID (e.g. com.despia.myapp), and check Push Notifications under Capabilities. Click Save. Without this, APNs will reject the registration even with a valid .p8 key.
5

Create the OneSignal Notification Service Extension bundle ID

Click + under Identifiers, choose App IDs, then App. Use a description like MyApp OneSignal Module and the bundle ID com.despia.myapp.OneSignalNotificationServiceExtension (your core bundle ID with .OneSignalNotificationServiceExtension appended). This exact naming is what Despia provisions during the build, do not change it. Under Capabilities, enable Associated Domains and Push Notifications.
6

Optional: enable App Groups for rich push and metrics

If you need delivery metrics, rich push notifications with images and action buttons, or any other advanced OneSignal features, also create an App Group. Click + under Identifiers, choose App Groups, and use the identifier group.com.despia.myapp.onesignal. Then add this group to both your core bundle ID and the OneSignalNotificationServiceExtension bundle ID under their App Groups capability. If you only need basic push, skip this step entirely, the integration works without an App Group for the standard delivery path.
7

Configure iOS in OneSignal

In OneSignal, go to Settings > Push & In-App > Apple iOS. Upload the .p8 file you downloaded, paste in your Key ID and Team ID, and enter your iOS bundle ID (e.g. com.despia.myapp). Click Save. OneSignal will validate the credentials with Apple immediately.
8

Set up a Firebase project for Android

Go to console.firebase.google.com, create a project (or use an existing one), and add an Android app with the same package name as your Despia app (e.g. com.despia.myapp). Then go to Project settings > Cloud Messaging to find your Server Key and Sender ID. If the legacy Server Key is hidden, enable the Cloud Messaging API in Google Cloud Console first.
9

Configure Android in OneSignal

In OneSignal, go to Settings > Push & In-App > Google Android. Paste in your Firebase Server Key and Sender ID. Click Save. OneSignal will validate the credentials with Google immediately.
10

Get your OneSignal App ID and REST API Key

In OneSignal, go to Settings > Keys & IDs. Copy the OneSignal App ID for client-side use, and the REST API Key for backend use. Keep the REST API Key on your server only, never bundle it into client code.
11

Enable OneSignal in the Despia Editor

Open the Despia Editor and go to App > Settings > Integrations > OneSignal. Toggle the integration on, then paste in your OneSignal App ID. If you created the App Group in the optional step above, also paste in group.com.despia.myapp.onesignal. Save the configuration.
12

Rebuild your app

Trigger a fresh build from the Despia Editor. The OneSignal SDK and the Notification Service Extension target have to be compiled into the app binary and signed against the bundle IDs you registered, so this cannot be applied over-the-air. After the rebuild, push notifications start working immediately.
Skipping the rebuild leaves OneSignal inactive even if the the correct OneSignal App IDs are added. The setonesignalplayerid:// call will resolve silently and your backend’s include_external_user_ids requests will succeed at the API level but never deliver to the device. If notifications stop arriving after editing settings, rebuild before opening a support ticket.

​
Critical alerts

Critical alerts bypass Do Not Disturb and silent mode, delivering the notification with sound regardless of the user’s device settings. They are intended for urgent, time-sensitive messages such as security alerts or medical notifications.

​
iOS

iOS requires the Critical Alerts entitlement from Apple. Request it at developer.apple.com/contact/request/notifications-critical-alerts-entitlement. Apple reviews requests manually and approval can take several weeks. When submitting the request, you need to enable the entitlement on two bundle IDs , your core app bundle ID and the OneSignal Notification Service Extension bundle ID you created in the Steps above. For example, if your app bundle ID is com.despia.myapp, add both:
  • com.despia.myapp
  • com.despia.myapp.OneSignalNotificationServiceExtension
Once Apple approves the request, enable critical alerts in Despia > App > Integrations > OneSignal > Critical Alerts and rebuild a new version in Despia. After the rebuild, set ios_critical_alert to 1 in your payload. 
// Backend: send a critical alert on iOS
const response = await fetch('https://onesignal.com/api/v1/notifications', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Basic YOUR_REST_API_KEY',
    },
    body: JSON.stringify({
        app_id:                     'YOUR_ONESIGNAL_APP_ID',
        include_external_user_ids:  [userId],
        headings:                   { en: 'Urgent alert' },
        contents:                   { en: 'Message body' },
        ios_critical_alert:         1,
    }),
})

​
Android

No dashboard configuration or rebuild is required. Set priority to 10 and android_channel_id to a high-importance channel in your OneSignal payload. To get your channel ID, go to OneSignal > Settings > Messaging > Android Categories and create a new category with importance set to Urgent. OneSignal will generate a channel ID for that category , copy it and use it as android_channel_id in your payload. 
// Backend: send a critical alert on Android
const response = await fetch('https://onesignal.com/api/v1/notifications', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Basic YOUR_REST_API_KEY',
    },
    body: JSON.stringify({
        app_id:                     'YOUR_ONESIGNAL_APP_ID',
        include_external_user_ids:  [userId],
        headings:                   { en: 'Urgent alert' },
        contents:                   { en: 'Message body' },
        priority:                   10,
        android_channel_id:         'YOUR_CHANNEL_ID', // from OneSignal > Settings > Messaging > Android Categories
    }),
})

​
Both platforms

To send a single critical alert that works on both Android and iOS, combine the fields in one payload. 
// Backend: send a critical alert on Android and iOS
const response = await fetch('https://onesignal.com/api/v1/notifications', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Basic YOUR_REST_API_KEY',
    },
    body: JSON.stringify({
        app_id:                     'YOUR_ONESIGNAL_APP_ID',
        include_external_user_ids:  [userId],
        headings:                   { en: 'Urgent alert' },
        contents:                   { en: 'Message body' },
        priority:                   10,
        android_channel_id:         'YOUR_CHANNEL_ID',
        ios_critical_alert:         1,
    }),
})

​
Resources

NPM Package

despia-native

OneSignal Dashboard

Configure your push notification app

REST API Reference

OneSignal Create Notification API

Support

support@despia.com