> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swiftaiboilerplate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OneSignal Push Notifications

> Add push notifications to your app with OneSignal SDK

<Info>
  **Complete setup guide:** See `/docs/integrations/OneSignal.md` in the project
</Info>

## What is OneSignal?

<CardGroup cols={2}>
  <Card title="Push Notifications" icon="bell">
    Send push notifications to engage users
  </Card>

  <Card title="Rich Notifications" icon="image">
    Images, buttons, badges, and custom sounds
  </Card>

  <Card title="Analytics" icon="chart-line">
    Confirmed delivery and engagement tracking
  </Card>

  <Card title="Segmentation" icon="users">
    Target users by behavior, tags, or segments
  </Card>
</CardGroup>

<Note>
  **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.
</Note>

## 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](https://onesignal.com) (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:

<Card title="OneSignal iOS SDK Setup" icon="arrow-up-right-from-square" href="https://documentation.onesignal.com/docs/ios-sdk-setup">
  Follow OneSignal's comprehensive step-by-step guide for iOS integration
</Card>

### Quick Overview

<Steps>
  <Step title="Create OneSignal Account">
    Go to [OneSignal](https://onesignal.com) and create a free account. The free tier includes unlimited push notifications for up to 10,000 subscribers.
  </Step>

  <Step title="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 →](https://documentation.onesignal.com/docs/ios-sdk-setup)
  </Step>

  <Step title="Add App ID to Config">
    After OneSignal setup, add your App ID to `Config/Secrets.xcconfig`:

    ```bash theme={null}
    ONESIGNAL_APP_ID = YOUR_ONESIGNAL_APP_ID
    ```
  </Step>

  <Step title="Run Update Config Script">
    Generate the Swift configuration:

    ```bash theme={null}
    bash scripts/update-config.sh
    ```
  </Step>

  <Step title="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
  </Step>
</Steps>

## How It Works

### Automatic Integration

The boilerplate automatically initializes OneSignal from `AppDelegate` when the App ID is configured:

```swift theme={null}
// AppDelegate.initializeOneSignal(launchOptions:) — runs automatically
let appId = AppConfiguration.ONESIGNAL_APP_ID

guard AppConfiguration.isConfigured("ONESIGNAL_APP_ID") else {
    AppLogger.error("OneSignal App ID not configured - push notifications disabled.",
                    category: AppLogger.notifications)
    return
}

OneSignal.initialize(appId, withLaunchOptions: launchOptions)
OneSignal.Notifications.requestPermission({ accepted in
    AppLogger.info("OneSignal notification permission: \(accepted ? "granted" : "denied")",
                   category: AppLogger.notifications)
}, fallbackToSettings: true)
```

**No code changes needed.** Just add the App ID to your config and rebuild.

### 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

<AccordionGroup>
  <Accordion title="Notifications not received">
    * 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
  </Accordion>

  <Accordion title="Rich notifications not showing images">
    * Verify Notification Service Extension is in your target
    * Check image URL is HTTPS
    * Ensure image is under 10MB
    * Test with a simple image first
  </Accordion>

  <Accordion title="OneSignal not initializing">
    * 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)
  </Accordion>
</AccordionGroup>

## 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

## Related Guides

<CardGroup cols={2}>
  <Card title="OneSignal Official Docs" icon="arrow-up-right-from-square" href="https://documentation.onesignal.com/docs/ios-sdk-setup">
    Comprehensive iOS SDK setup guide
  </Card>

  <Card title="Supabase Setup" icon="database" href="/pages/guides/supabase-setup">
    Backend configuration
  </Card>

  <Card title="Crashlytics Setup" icon="bug" href="/pages/guides/crashlytics-setup">
    Another optional integration
  </Card>

  <Card title="Deployment" icon="rocket" href="/pages/guides/deployment">
    Ship to App Store
  </Card>
</CardGroup>

## Need Help?

* 📖 Check the troubleshooting section above
* 📚 See `/docs/integrations/OneSignal.md` in your project
* 💬 [Create an issue](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/issues)
* 🔍 Search [OneSignal docs](https://documentation.onesignal.com)