The Sendrealm iOS SDK connects your iPhone and iPad app to Sendrealm mobile push. It registers APNs device tokens, sends those tokens to Sendrealm, tracks notification lifecycle events, manages subscription state, links devices to users, stores app-sourced tags, and handles Sendrealm APNs payloads consistently.
Use this guide for native Swift or Objective-C iOS apps. If your app is built with React Native, start with React Native Bare SDK or React Native Expo SDK.
How iOS Push Works
iOS push delivery uses Apple Push Notification service, usually called APNs.
- Your app asks iOS for notification permission.
- iOS gives your app an APNs device token.
- Your app forwards that token to the Sendrealm SDK.
- The SDK registers the token with Sendrealm.
- Sendrealm uses your APNs key to send notifications to that token.
Sendrealm cannot send an iOS notification until both sides are ready: the dashboard must have valid APNs credentials, and the app must register an APNs token from a real device.
Use a physical iOS device for end-to-end APNs testing. Simulators are useful for UI work, but physical devices are the reliable path for push token and delivery testing.
Setup Order
Follow this order:
- Create or select your Sendrealm app in the dashboard.
- Confirm the iOS Bundle ID and enable Push Notifications on the App ID in Apple Developer.
- Enable Push Notifications in your Xcode app target.
- Create an APNs
.p8 key in Apple Developer.
- Upload the
.p8 key, Key ID, Team ID, Bundle ID, and environment to Sendrealm.
- Install the Sendrealm iOS SDK.
- Configure and initialize the SDK.
- Forward APNs token callbacks from your app delegate.
- Ask the user for notification permission.
- Send a test push from Sendrealm.
Requirements
- iOS 13.4 or newer
- Swift Package Manager or CocoaPods
- A Sendrealm app ID from the dashboard
- Push Notifications enabled on the Apple Developer App ID
- Push Notifications capability enabled in Xcode
- An APNs authentication key uploaded in the Sendrealm dashboard
- A physical iOS device for end-to-end APNs testing
Use sandbox APNs environment for development builds. Use production for production-signed builds, including TestFlight and App Store distribution.
APNs Credential Requirement
Sendrealm sends iOS notifications through APNs. For that to work, Sendrealm needs:
- The
.p8 APNs private key file
- The Apple Key ID
- The Apple Team ID
- The app Bundle ID
- The APNs environment, either
sandbox or production
See Mobile Push Credentials for the full APNs credential walkthrough.
Enable Push Notifications For The Apple App ID
Apple must allow the app Bundle ID to use push notifications before APNs delivery can work.
- Open Certificates, Identifiers & Profiles.
- Open Identifiers.
- Select the App ID that matches your app Bundle ID.
- Click Edit.
- Enable Push Notifications.
- Save the App ID changes.
If you are creating a new App ID, use an explicit Bundle ID that exactly matches the Bundle Identifier in your Xcode app target. The Bundle ID is the APNs topic. If Sendrealm sends to com.example.app, but the installed app is signed as com.example.app.dev, APNs treats those as different apps.
Apple requires an Account Holder or Admin role to manage App ID capabilities. When an App ID capability changes, existing provisioning profiles that include that App ID can become invalid. If Xcode signing starts failing after enabling Push Notifications, refresh automatic signing or regenerate the provisioning profile.
Enable Capabilities In Xcode
The Apple Developer App ID controls what the team is allowed to sign. The Xcode target controls what your actual app requests at build time. Both sides must match.
In Xcode:
- Open your
.xcodeproj or .xcworkspace.
- Select the app project in the left navigator.
- Select the iOS app target.
- Open Signing & Capabilities.
- Click the add capability button.
- Add Push Notifications.
- Confirm the target still uses the expected Team and Bundle Identifier.
Adding Push Notifications gives the app the push notification entitlement, including the APNs environment entitlement used by development and production builds.
If you send silent pushes or background update notifications, also add Background Modes:
- In the same app target, open Signing & Capabilities.
- Click the add capability button.
- Add Background Modes.
- Check Remote notifications.
Only enable Remote notifications when your app actually handles background push work. iOS treats silent/background delivery as best effort and may throttle it.
If you send rich image notifications, add a Notification Service Extension target. That extension is separate from the Push Notifications capability. It gives iOS a short window to download media and attach it before displaying the notification.
Create The APNs Key For Sendrealm
Sendrealm needs an APNs private key so it can authenticate with Apple when sending notifications for your app.
In Apple Developer:
- Open Certificates, Identifiers & Profiles.
- Open Keys.
- Click the add button.
- Enter a clear name, for example
Sendrealm Push.
- Select Apple Push Notification service.
- Click Configure next to Apple Push Notification service.
- Choose the APNs key scope Apple offers for your account.
- Confirm the key configuration.
- Download the
.p8 private key immediately.
Apple private keys can only be downloaded once. Store the .p8 file in a secure secret manager after uploading it to Sendrealm.
The APNs key must include Apple Push Notification service. A key created for another Apple service cannot send push notifications. Apple requires an Account Holder or Admin role to create keys.
Some Apple accounts can choose a Team Scoped or Topic Specific APNs key:
- Team Scoped is the simplest option and can authenticate APNs sends for apps owned by the same Apple team.
- Topic Specific restricts the key to selected APNs topics. If you choose Topic Specific, include the exact Bundle ID used by this app.
Upload these values in Sendrealm:
- The
.p8 file
- Key ID
- Team ID
- Bundle ID
- APNs environment, either
sandbox or production
Install With Swift Package Manager
In Xcode:
- Open your project.
- Choose File, then Add Package Dependencies.
- Enter the Sendrealm iOS SDK repository URL.
- Add the
SendrealmIOS product to your app target.
https://github.com/sendrealm/ios.git
sdks/ios package.
Install With CocoaPods
Add the pod to your Podfile:
Then install pods:
Open the generated .xcworkspace after installing pods.
Initialize
Configure and initialize the SDK during app startup:
import SendrealmIOS
Sendrealm.configure()
Sendrealm.shared.initialize([
"appId": "YOUR_SENDREALM_APP_ID",
"apnsEnvironment": "sandbox",
"autoRequestPermission": false
]) { result, error in
print(result as Any, error as Any)
}
- Stores your Sendrealm app ID.
- Creates or restores the Sendrealm device ID.
- Stores the selected APNs environment.
- Registers the latest APNs token with Sendrealm when a token is available.
- Persists identity and subscription state.
- Enables notification tracking and foreground notification handling.
Most apps should set autoRequestPermission to false and request permission after explaining the value of notifications.
APNs Environment
APNs has separate development and production environments. The token from one environment cannot be sent through the other environment.
| Build type | Use this environment |
|---|
| Xcode debug or development-signed build | sandbox |
| TestFlight | production |
| App Store | production |
| Production-signed ad hoc build | production |
Forward APNs Tokens
iOS delivers APNs tokens through app delegate callbacks. Your app must forward those callbacks to Sendrealm.
func application(
_ application: UIApplication,
didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
Sendrealm.didRegisterForRemoteNotifications(withDeviceToken: deviceToken)
}
Notification Permission
Ask for permission after your app explains what the user will receive:
Sendrealm.shared.requestPermission { granted, error in
print(granted?.boolValue == true, error as Any)
}
Sendrealm.shared.getPermissionStatus { status in
print(status as Any)
}
Sendrealm.shared.openNotificationSettings { opened in
print(opened.boolValue)
}
Foreground Display
By default, iOS may treat foreground notifications differently from background notifications. Configure foreground presentation when you want notifications to appear while the app is open:
Sendrealm.shared.setForegroundPresentation([
"banner": true,
"list": true,
"sound": true,
"badge": true
]) { success in
print(success.boolValue)
}
Identity
Link the device after login:
Sendrealm.shared.login("user-123", email: "user@example.com") { error in
print(error as Any)
}
logout when the user signs out so the device is no longer linked to the previous user.
Tags are values observed by the app. Use them for preferences, state, and behavior that the app can safely report.
Sendrealm.shared.addTags([
"plan": "pro",
"onboardingComplete": true
]) { success, error in
print(success.boolValue)
print(error as Any)
}
plan = "pro"preferredLanguage = "en"onboardingComplete = truefavoriteCategory = "travel"
Do not use SDK tags for authoritative account, billing, security, compliance, or verified profile data. Update those from your backend.
Custom Events
Use custom events for behavior that should drive segmentation or automations:
Sendrealm.shared.trackEvent("checkout_started", properties: [
"product_id": "sku_123",
"price": 29
]) { success, error in
print(success.boolValue)
print(error as Any)
}
Rich Notifications
Rich image notifications require a Notification Service Extension. The extension gets a short window to download media and attach it before iOS displays the notification.
In the extension target, call the helper:
SendrealmNotificationServiceHelper.enrich(
request: request,
bestAttemptContent: bestAttemptContent,
completion: contentHandler
)
Silent Pushes
Silent pushes are background notifications. They do not show an alert by themselves.
Silent pushes require:
- Remote notifications background mode enabled.
- APNs
content-available payload.
- A device and OS state that allows background execution.
Delivery is best effort under iOS power policy. Do not rely on silent pushes for urgent user-visible work.
Delivery Timing And OS Behavior
iOS notification delivery and display are controlled by APNs and the operating system. Sendrealm can send a valid notification to APNs, but the final result still depends on APNs priority, device connectivity, device power state, app state, user notification settings, Focus modes, and iOS background execution rules.
Visible alerts should use normal alert-style notification behavior. Background updates and silent pushes are different: APNs treats background update notifications as low priority, and iOS may throttle them or skip delivery when conditions are not favorable.
You may see delayed or missing notifications when:
- The device is offline or has poor network connectivity.
- The APNs environment does not match the build.
- The user disabled notifications, sounds, badges, or alert display.
- Focus or notification summary settings hide or defer alerts.
- The notification is background-only or low priority.
- Too many background updates are sent in a short period.
- The app has not forwarded the latest APNs token to Sendrealm.
- The device token is stale or no longer valid for the Bundle ID.
Treat push delivery as best effort. Keep important app state available from your backend when the user opens the app, and avoid using silent push as the only path for critical behavior.
Testing Checklist
Before going to production, confirm:
- The app initializes without SDK errors.
- The app asks for notification permission at the expected moment.
- Permission status becomes authorized after the user accepts.
- The Apple Developer App ID has Push Notifications enabled.
- The Xcode app target has Push Notifications enabled.
- Background Modes includes Remote notifications if you use silent/background pushes.
- APNs token callbacks are forwarded to Sendrealm.
- Diagnostics show token presence.
- APNs environment matches the build type.
- Bundle ID, Team ID, Key ID, and
.p8 key match the app.
- A test push arrives on a physical device.
- Time-sensitive alerts use visible notification payloads.
- Background updates still make sense if they are delayed or skipped.
- Tapping a notification opens the expected screen or URL.
- Rich images work if you use image notifications.
Diagnostics
Use diagnostics when testing:
Sendrealm.shared.getDiagnostics { diagnostics in
print(diagnostics as Any)
}
deviceId: should be present after initialization.registrationTokenPresent: should be true after APNs token forwarding.apnsEnvironment: should match the current build.permissionStatus: should be authorized, provisional, or another expected iOS status.lastSdkError: should explain the latest SDK failure, if any.
Troubleshooting
| Symptom | What to check |
|---|
| APNs token never registers | Confirm token callbacks are forwarded from AppDelegate. |
| Development push fails | Confirm apnsEnvironment is sandbox and the build is development-signed. |
| TestFlight or App Store push fails | Confirm apnsEnvironment is production. |
| Push entitlement is missing | Enable Push Notifications on the Apple Developer App ID and in the Xcode app target. |
| Signing fails after enabling push | Refresh automatic signing or regenerate the provisioning profile for the App ID. |
| APNs key is rejected | Confirm the key has Apple Push Notification service enabled and belongs to the same Apple team. |
| Push does not arrive on simulator | Test on a physical device. |
| Notifications are delayed | Check APNs priority, device connectivity, Focus settings, notification settings, and whether the payload is background-only. |
| Silent pushes are inconsistent | This is expected under iOS power policy; use silent pushes only for best-effort refresh work. |
| Rich images do not attach | Confirm the Notification Service Extension is installed and receives the payload. |
Tags fail with ContactNotLinked | Call login(userId, email) before setting user tags. |
Related Pages
