OneSignal Push Notifications

Overview

Remote push notifications allow you to send messages to users even when your app is closed. Unlike local notifications, these are triggered from your server and can be targeted to specific users, groups, or all users based on your backend logic.

Prerequisites

OneSignal Setup

1. Create a OneSignal account

2. Create a new app/website in OneSignal

3. Configure iOS and Android platforms

Despia Configuration

1. Have your Despia project ready

2. Link it to your WeWeb application

WeWeb Setup

1. Install Despia plugin from WeWeb Marketplace

2. Verify installation: Assets → Library → check for "Despia"

Platform Configuration

iOS Setup

Step 1: Create Apple Push Key

1. Go to Apple Developer

2. Navigate to Keys

3. Create new key with name (e.g., "MyApp Push")

4. Enable Apple Push Notifications service

5. Download the .p8 file (keep it secure - can only download once)

Step 2: Configure OneSignal for iOS

1. In OneSignal, select Apple iOS platform

2. Upload your .p8 file

3. Enter Key ID (from Apple Developer)

4. Enter Team ID (top right in Apple Developer)

5. Enter Bundle ID (from Despia → Publish App)

6. Select Native iOS (not React Native)

7. Save and continue

Android Setup

Step 1: Create Firebase Project

1. Go to Firebase Console

2. Create new project

3. Navigate to Project Settings → Cloud Messaging

4. Verify FCM API v1 is enabled

Step 2: Generate Service Account

1. Go to Service Accounts tab

2. Click Generate new private key

3. Download the JSON file (keep secure)

Step 3: Configure OneSignal for Android

1. In OneSignal, activate Google Android

2. Upload Firebase service account JSON

3. Select Native Android

4. Save and continue

Despia Integration

Add OneSignal App IDs

1. Copy App ID from OneSignal

2. In Despia editor, paste into:

   • iOS Application ID field

   • Android Application ID field (often same ID)

3. Save configuration

WeWeb Implementation

Step 1: Add Despia Plugin Component

1. Click Add → Assets

2. Drag Despia plugin to top of page

3. This exposes the OneSignal Player ID variable

Step 2: Access Player ID

The plugin provides access to:

• onesignalplayerid: Unique device identifier

• Use this to target specific devices

Step 3: Store Player ID on Login

During user authentication:

1. Add Player ID parameter to login request

2. Store in your database linked to user account

3. Handle multiple devices per user (use array/table)

Backend Integration

API Configuration Example (Xano)

1. Create external API endpoint

2. Import OneSignal cURL command

3. Configure with:

   • App ID: From OneSignal

   • API Key: From OneSignal Settings → Keys & IDs

   • Player IDs: Array of target devices

   • Message content: Title and body

Copycurl -X POST https://onesignal.com/api/v1/notifications \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Basic YOUR_REST_API_KEY" \
  -d '{
    "app_id": "ONESIGNAL-APP-ID",
    "include_player_ids": ["PLAYER-ID"],
    "headings": {"en": "Hello"},
    "contents": {"en": "This is a test notification from Despia"}
  }'

Sending Notifications

Target specific users by:

1. Query user's linked Player IDs

2. Include in OneSignal API request

3. Send notification to all user's devices

Player ID Management

Important Considerations

• Player IDs may change when users switch accounts

• One user can have multiple Player IDs (multiple devices)

• Handle device switching logic in backend

Best Practices

1. On Login: Update Player ID association

2. On Logout: Consider removing Player ID

3. Account Switching: Transfer Player ID to new account

4. Multiple Devices: Store as array/list reference

Publishing & Deployment

When to Rebuild App

Rebuild in Despia when changing:

• OneSignal App IDs

• Start URL

• App name or icon

• Any Despia editor settings

Over-the-Air Updates

WeWeb changes update automatically:

• No rebuild needed for WeWeb changes

• Instant deployment to all users

• No App Store resubmission

Testing Push Notifications

1. Deploy app with OneSignal configuration

2. Install on test device via TestFlight/Beta

3. Copy Player ID from app

4. Send test notification from backend

5. Verify receipt on device

Common Use Cases

E-commerce

• Order status updates

• Shipping notifications

• Promotional offers

• Cart abandonment reminders

Social Apps

• New messages

• Friend requests

• Content interactions

• Event reminders

Business Apps

• Task assignments

• Meeting reminders

• Approval requests

• System alerts

Troubleshooting

Notifications not received:

• Verify OneSignal configuration

• Check Player ID is correct

• Ensure app permissions granted

• Test with OneSignal dashboard first

Wrong user receiving notifications:

• Check Player ID associations

• Verify account switching logic

• Review database relationships

iOS specific issues:

• Verify .p8 key is valid

• Check bundle ID matches

• Ensure push entitlement enabled

Android specific issues:

• Verify FCM is enabled

• Check Firebase configuration

• Review service account permissions