iOS Push Notifications Setup

Complete guide to setting up Apple Push Notifications (APNs) for your iOS app with Retenshun.

Prerequisites

  • Apple Developer account ($99/year) — developer.apple.com
  • Xcode installed on a Mac
  • A physical iOS device (push notifications don't work on simulator)
  • Retenshun SDK integrated in your app
1

Enable Push in Xcode

Open your project in Xcode

For Flutter: Open ios/Runner.xcworkspace (not .xcodeproj)

For React Native: Open ios/YourApp.xcworkspace

For native Swift/ObjC: Open your .xcodeproj or .xcworkspace

Add Push Notifications capability

  1. Select your app target (e.g. Runner) in the left sidebar
  2. Click the Signing & Capabilities tab
  3. Click + Capability in the top left
  4. Search for and add Push Notifications

This adds the aps-environment entitlement to your app.

Add Background Modes capability

  1. Click + Capability again
  2. Search for and add Background Modes
  3. Check Remote notifications

This allows your app to receive push notifications in the background and perform silent updates.

2

Generate an APNs Authentication Key (.p8)

Important: Save your .p8 file!

Apple only lets you download the .p8 key file once. If you lose it, you must create a new key. Store it securely.

Steps in Apple Developer Portal

  1. Go to Certificates, Identifiers & Profiles → Keys

    Direct link: developer.apple.com/account/resources/authkeys/list

  2. Click the + button to create a new key
  3. Enter a name (e.g. "Retenshun Push Key")
  4. Check Apple Push Notifications service (APNs)
  5. Click Continue → Register
  6. Download the .p8 file immediately! Save it somewhere safe.
  7. Note the Key ID shown on the confirmation page (10 characters, e.g. ABC123DEF4)

Find your Team ID

  1. Go to Account → Membership Details
  2. Your Team ID is a 10-character alphanumeric string (e.g. 9ABCDE1234)

You now have 3 values

ValueExampleWhere to find
.p8 fileAuthKey_ABC123DEF4.p8Downloaded after key creation
Key IDABC123DEF4Key confirmation page
Team ID9ABCDE1234Membership Details page
3

Add APNs Key to Push Provider

Option A: Using default Retenshun push (recommended)

Contact the Retenshun team to upload your APNs key to the shared push infrastructure. Provide:

  • Your .p8 file
  • Key ID
  • Team ID
  • Bundle ID (e.g. com.yourcompany.yourapp)

Option B: Using your own OneSignal app

  1. Go to OneSignal Dashboard → your app → Settings → Platforms
  2. Click Apple iOS (APNs)
  3. Select .p8 Auth Key (Token Based) — Recommended
  4. Upload your .p8 file
  5. Enter your Key ID
  6. Enter your Team ID
  7. Enter your Bundle ID (must match your Xcode target)
  8. Click Save

The .p8 key is recommended over .p12 certificates because it never expires and works for all your apps under the same Apple Developer account.

4

Test on a Real Device

Build and run on your iPhone/iPad

  1. Connect your device via USB or use wireless debugging
  2. Select your device as the build target in Xcode / VS Code
  3. Run the app — it should prompt for notification permission
  4. Tap Allow
  5. Check your Retenshun dashboard — the device should appear under registered devices

Send a test push

curl -X POST https://your-retenshun-domain.com/api/v1/messages \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "your_user_id",
    "channel": "push",
    "content": {
      "title": "iOS Push Test",
      "body": "If you see this, iOS push is working!"
    }
  }'

Troubleshooting

No permission prompt appears

  • Make sure you're running on a real device (not simulator)
  • Check that Push Notifications capability is added in Xcode
  • Check Settings → your app → Notifications to see if permission was already denied
  • Try deleting the app and reinstalling

Permission granted but no notifications received

  • Verify your APNs key is uploaded correctly (Key ID, Team ID, Bundle ID must all match)
  • Check if using sandbox vs production — debug builds use sandbox APNs, release builds use production
  • Wait 1-2 minutes — iOS push delivery can be delayed
  • Check OneSignal delivery report for errors

Notifications arrive but without sound

  • Check device is not in Focus/Do Not Disturb mode
  • Check Settings → your app → Notifications → Sounds is enabled

"InvalidProviderToken" or "BadDeviceToken" errors

  • InvalidProviderToken: Key ID or Team ID is wrong, or .p8 file is from a different account
  • BadDeviceToken: The token was generated in sandbox but sent to production, or vice versa
  • Make sure the Bundle ID in OneSignal matches your Xcode target exactly

.p8 Key vs .p12 Certificate

.p8 Key (Recommended).p12 Certificate
ExpiresNeverEvery year
Works forAll apps in your accountOne app only
EnvironmentSandbox + ProductionSeparate certs needed
Setup3 clicks in Apple portalComplex Keychain process

What's Next?

Flutter SDK

Full SDK reference

React SDK

Web push setup

REST API

Server-side sending

Quick Start

Get started in 5 minutes