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

# iOS SDK reference

> Reference iOS initialization options, methods, state, and notification models.

## Configuration

```swift theme={null}
let configuration = PushctlConfiguration(
    applicationKey: "push_live_your_client_token",
    apiURL: URL(string: "https://pushctl.com/api/v1")!,
    appGroupIdentifier: "group.com.example.app.pushctl"
)

Pushctl.shared.configure(configuration)
```

| Member                                            | Purpose                                                                   |
| ------------------------------------------------- | ------------------------------------------------------------------------- |
| `Pushctl.initialize(...)`                         | Configure the shared instance                                             |
| `requestPermission()`                             | Request permission and return whether it was granted                      |
| `setDeviceToken(Data)`                            | Start registration with the APNs token supplied by UIKit                  |
| `setDeviceToken(String)`                          | Start registration with an encoded APNs token                             |
| `register(deviceToken:)`                          | Register a UIKit APNs token and await the API result                      |
| `register(token:)`                                | Register an encoded APNs token and await the API result                   |
| `waitForRegistration(timeout:)`                   | Wait for confirmed registration; defaults to 15 seconds                   |
| `reportRemoteNotificationRegistrationFailure(_:)` | Forward an APNs registration failure from the app delegate                |
| `login(_:)`                                       | Associate the installation with an external user and await the API result |
| `logout()`                                        | Remove the user association and await the API result                      |
| `subscriptionState`                               | Read installation, identity, permission, token, and registration state    |
| `subscriptionRegistered`                          | Callback after confirmed server registration                              |
| `registrationFailed`                              | Callback for APNs, API, or timeout registration failure                   |
| `notificationOpened`                              | Callback for user interaction                                             |
| `notificationWillDisplay`                         | Callback before foreground display                                        |

`register`, `waitForRegistration`, `login`, and `logout` are `async throws`. Login and logout require a confirmed installation and update local identity only after the API accepts the change.

## Subscription state

`PushctlSubscriptionState` contains `installationId`, `externalUserId`, `permission`, `pushToken`, `registrationStatus`, and `registrationError`. Its computed `isRegistered` property is `true` only when `registrationStatus` is `.registered`.

Registration status can be `unregistered`, `registering`, `registered`, or `failed`.

## Permission values

`unknown`, `not_determined`, `authorized`, `provisional`, `ephemeral`, and `denied`.

<Expandable title="Notification model">
  `PushctlNotification` provides `notificationId`, `deliveryId`, optional `title`, `body`, `imageURL`, and `actionURL`, plus `data: [String: String]`.
</Expandable>

<Info>The production endpoint requires HTTPS. HTTP is allowed only for localhost or `.test` development hosts.</Info>