Skip to main content
Complete setup guide: See /docs/integrations/OneSignal.md in the project

​
What is OneSignal?

Push Notifications

Send push notifications to engage users

Rich Notifications

Images, buttons, badges, and custom sounds

Analytics

Confirmed delivery and engagement tracking

Segmentation

Target users by behavior, tags, or segments
Optional Integration: OneSignal is completely optional. Your app works perfectly fine without it. Simply don’t configure the App ID if you don’t need push notifications.

​
Features Included

  • ✅ Push notifications via OneSignal SDK
  • ✅ Rich notifications with images, buttons, and badges
  • ✅ Confirmed delivery analytics
  • ✅ User segmentation support
  • ✅ In-app messaging capability
  • ✅ Notification Service Extension pre-configured
  • ✅ Graceful degradation (works without configuration)

​
Prerequisites

  • OneSignal account (free tier available)
  • Apple Developer account (for push certificate)
  • App ID with Push Notifications capability enabled

​
Setup Guide

OneSignal provides excellent, regularly-updated documentation for iOS SDK setup. We recommend following their official guide:

OneSignal iOS SDK Setup

Follow OneSignal’s comprehensive step-by-step guide for iOS integration

​
Quick Overview

1

Create OneSignal Account

Go to OneSignal and create a free account. The free tier includes unlimited push notifications for up to 10,000 subscribers.
2

Follow OneSignal's iOS Setup

Their guide covers:
  • Adding Push Notifications capability
  • Configuring Background Modes
  • Setting up App Groups
  • Adding Notification Service Extension
  • Installing the SDK
Open OneSignal iOS SDK Setup →
3

Add App ID to Config

After OneSignal setup, add your App ID to Config/Secrets.xcconfig:
ONESIGNAL_APP_ID = your-onesignal-app-id-here
4

Run Update Config Script

Generate the Swift configuration:
bash scripts/update-config.sh
5

Build and Test

Build and run on a real device (push notifications don’t work in simulator):
  1. Run the app
  2. Accept push notification permission
  3. Send a test notification from OneSignal dashboard
  4. Verify notification appears on device

​
How It Works

​
Automatic Integration

The boilerplate automatically initializes OneSignal when the App ID is configured: 
// In AppDelegate (automatic)
if let appId = Configuration.oneSignalAppId, !appId.isEmpty {
    OneSignal.initialize(appId)
    OneSignal.Notifications.requestPermission { accepted in
        print("Push permission: \(accepted)")
    }
}
No code changes needed! Just add the App ID to your config.

​
Graceful Degradation

If OneSignal is not configured:
  • App launches normally
  • No SDK initialization
  • No errors or crashes
  • Push notification code paths are skipped

​
Removing OneSignal

If you don’t need push notifications:
  1. Leave ONESIGNAL_APP_ID empty in Secrets.xcconfig
  2. The SDK won’t initialize
  3. No push notification code will run
To completely remove:
  1. Remove OneSignal package from Swift Package Manager
  2. Delete the Notification Service Extension target
  3. Remove OneSignal references from code
  4. See /docs/integrations/OneSignal.md for complete removal guide

​
Troubleshooting

  • Test on a real device (not simulator)
  • Verify APNs certificate/key is correct in OneSignal
  • Check Push Notifications capability is enabled in Xcode
  • Ensure user accepted notification permission
  • Check OneSignal dashboard for delivery status
  • Verify Notification Service Extension is in your target
  • Check image URL is HTTPS
  • Ensure image is under 10MB
  • Test with a simple image first
  • Verify ONESIGNAL_APP_ID is set in Secrets.xcconfig
  • Run bash scripts/update-config.sh
  • Check Configuration.swift has the App ID
  • Clean and rebuild (⌘⇧K then ⌘B)

​
Cost

OneSignal Free Tier:
  • ✅ Unlimited push notifications
  • ✅ Up to 10,000 subscribers
  • ✅ Basic analytics
  • ✅ Enough for most indie apps
Paid Plans:
  • More subscribers
  • Advanced analytics
  • A/B testing
  • Priority support

OneSignal Official Docs

Comprehensive iOS SDK setup guide

Supabase Setup

Backend configuration

Crashlytics Setup

Another optional integration

Deployment

Ship to App Store

​
Need Help?

  • 📖 Check the troubleshooting section above
  • 📚 See /docs/integrations/OneSignal.md in your project
  • 💬 Create an issue
  • 🔍 Search OneSignal docs