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

# iOS SDK

> Install and initialize the Sendrealm iOS SDK.

Use the Sendrealm iOS SDK to receive mobile push notifications in native Swift or Objective-C iOS apps.

If your app uses React Native, start with [React Native Bare SDK](/sdks/react-native-bare) or [React Native Expo SDK](/sdks/react-native-expo).

## Requirements

* iOS 13.4 or newer.
* A Sendrealm app ID from the dashboard.
* Push Notifications enabled for the Apple App ID.
* Push Notifications enabled on the Xcode target.
* APNs credentials uploaded in Sendrealm.
* A physical iOS device for end-to-end push testing.

Use `sandbox` for development builds installed from Xcode. Use `production` for TestFlight and App Store builds.

See [Mobile Push Credentials](/tutorials/mobile-push-credentials) for APNs setup.

## Install With Swift Package Manager

In Xcode:

1. Open your project.
2. Choose File, then Add Package Dependencies.
3. Enter the Sendrealm iOS SDK repository URL.
4. Add the `SendrealmIOS` product to your app target.

```text theme={null}
https://github.com/sendrealm/ios.git
```

## Install With CocoaPods

Add the pod to your `Podfile`:

```ruby theme={null}
pod "SendrealmIOS"
```

Then install pods:

```bash theme={null}
pod install
```

Open the generated `.xcworkspace` after installing pods.

## Enable iOS Capabilities

In Xcode:

1. Open your app target.
2. Open Signing & Capabilities.
3. Add Push Notifications.
4. Confirm the Team and Bundle Identifier match the app configured in Sendrealm.

If your app sends background updates, add Background Modes and check Remote notifications.

If your app sends rich image notifications, add a Notification Service Extension target.

## Initialize

Configure and initialize during app startup:

```swift theme={null}
import SendrealmIOS

Sendrealm.configure()

Sendrealm.shared.initialize([
  "appId": "YOUR_SENDREALM_APP_ID",
  "environment": "development",
  "apnsEnvironment": "sandbox",
  "autoRequestPermission": false
]) { result, error in
  print(result as Any, error as Any)
}
```

Use `environment: "development"` for test devices you want to target separately. Omit it for production.

Set `apnsEnvironment` based on the build:

| Build type                              | APNs environment |
| --------------------------------------- | ---------------- |
| Xcode debug or development-signed build | `sandbox`        |
| TestFlight                              | `production`     |
| App Store                               | `production`     |
| Production-signed ad hoc build          | `production`     |

Most apps should set `autoRequestPermission` to `false` and ask for permission after explaining the value of notifications.

## Register For Push

Add the standard app delegate callback so Sendrealm can complete iOS push registration:

```swift theme={null}
func application(
  _ application: UIApplication,
  didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
  Sendrealm.didRegisterForRemoteNotifications(withDeviceToken: deviceToken)
}
```

## Ask For Permission

Ask for permission from a user action:

```swift theme={null}
Sendrealm.shared.requestPermission { granted, error in
  print(granted?.boolValue == true, error as Any)
}
```

Read permission status:

```swift theme={null}
Sendrealm.shared.getPermissionStatus { status in
  print(status as Any)
}
```

iOS users can deny notifications, change alert style, disable sounds, disable badges, or use Focus settings. Permission status helps you decide what to show in your app UI.

## Foreground Display

Configure foreground presentation when notifications should appear while the app is open:

```swift theme={null}
Sendrealm.shared.setForegroundPresentation([
  "banner": true,
  "list": true,
  "sound": true,
  "badge": true
]) { success in
  print(success.boolValue)
}
```

## Link A Signed-In User

Call `login` after the user signs in:

```swift theme={null}
Sendrealm.shared.login("user-123", email: "user@example.com") { error in
  print(error as Any)
}
```

Call `logout` when the user signs out.

## Tags

Use tags for app-observed preferences, state, and behavior:

```swift theme={null}
Sendrealm.shared.addTags([
  "plan": "pro",
  "onboardingComplete": true
]) { success, error in
  print(success.boolValue)
  print(error as Any)
}
```

Do not use SDK tags for authoritative account, billing, security, compliance, or verified profile data. Update those values from your backend.

## Custom Events

Track app events for segmentation, analytics, or automations:

```swift theme={null}
Sendrealm.shared.trackEvent("checkout_started", properties: [
  "product_id": "sku_123",
  "price": 29
]) { success, error in
  print(success.boolValue)
  print(error as Any)
}
```

Use stable event names and avoid sending sensitive data unless your team intentionally wants that data stored in Sendrealm.

## Rich Notifications

Rich image notifications require a Notification Service Extension. In the extension target, call the Sendrealm helper:

```swift theme={null}
SendrealmNotificationServiceHelper.enrich(
  request: request,
  bestAttemptContent: bestAttemptContent,
  completion: contentHandler
)
```

If the image cannot be downloaded in time, iOS should still display the notification without the image.

## Silent Pushes

Silent pushes require Background Modes with Remote notifications enabled. Delivery is best effort and can be throttled by iOS.

Do not rely on silent pushes as the only path for critical user-visible work.

## Diagnostics

Use diagnostics while testing:

```swift theme={null}
Sendrealm.shared.getDiagnostics { diagnostics in
  print(diagnostics as Any)
}
```

Confirm diagnostics show:

* A device ID.
* Token presence.
* Expected APNs environment.
* Expected permission status.
* Subscribed state unless the user opted out.
* No unexpected SDK error.

## Troubleshooting

| Symptom                            | What to check                                                                                      |
| ---------------------------------- | -------------------------------------------------------------------------------------------------- |
| Token is missing                   | Test on a physical device and confirm Push Notifications are enabled in Apple Developer and Xcode. |
| Development push fails             | Confirm `apnsEnvironment` is `sandbox` and the build is development-signed.                        |
| TestFlight or App Store push fails | Confirm `apnsEnvironment` is `production`.                                                         |
| Signing fails after enabling push  | Refresh automatic signing or regenerate the provisioning profile.                                  |
| Notifications are delayed          | Check APNs priority, device connectivity, Focus settings, and notification settings.               |
| 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 included in the app build.                           |
| Tags fail with `ContactNotLinked`  | Call `login(userId, email)` before setting user tags.                                              |

## Related Pages

* [Mobile Push Credentials](/tutorials/mobile-push-credentials)
* [Send Push Notification API](/api-reference/endpoint/send-push-notification)
* [React Native Bare SDK](/sdks/react-native-bare)