Skip to main content
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 dashboard setup

Before calling setonesignalplayerid://, configure OneSignal with your iOS and Android credentials.
1

Create a OneSignal account

Go to onesignal.com and create an app. When selecting platforms, choose Native iOS and Native Android, Despia apps are native applications, not web apps.
2

Configure iOS (Apple Push Key)

In OneSignal, go to Settings > Push & In-App > Apple iOS. Upload your .p8 Auth Key from Apple Developer Console under Certificates, Identifiers & Profiles > Keys. You will need your Key ID and Team ID.
3

Configure Android (Firebase)

In OneSignal, go to Settings > Push & In-App > Google Android. Enter your Firebase Server Key and Sender ID from your Firebase project settings under Cloud Messaging.
4

Add your OneSignal App ID to Despia

Copy your OneSignal App ID and add it in Despia > App > Settings > Integrations > OneSignal.

​
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 your OneSignal Service Extension bundle ID. 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