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.

​
Resources

NPM Package

despia-native

OneSignal Dashboard

Configure your push notification app

REST API Reference

OneSignal Create Notification API

Support

support@despia.com