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

# Capacitor SDK reference

> Reference Capacitor plugin methods, options, permission states, and events.

## Methods

| Method                      | Returns                         | Purpose                                                     |
| --------------------------- | ------------------------------- | ----------------------------------------------------------- |
| `initialize(options)`       | `Promise<void>`                 | Configure the native SDK                                    |
| `requestPermission()`       | `Promise<PermissionResult>`     | Request and synchronize permission                          |
| `waitForRegistration()`     | `Promise<SubscriptionState>`    | Wait up to 15 seconds for confirmed server registration     |
| `login({ externalUserId })` | `Promise<void>`                 | Associate an external user after the API accepts the update |
| `logout()`                  | `Promise<void>`                 | Remove that association after the API accepts the update    |
| `getSubscriptionState()`    | `Promise<SubscriptionState>`    | Read installation and permission state                      |
| `addListener(...)`          | `Promise<PluginListenerHandle>` | Observe registration or notification events                 |
| `removeAllListeners()`      | `Promise<void>`                 | Remove every plugin listener                                |

`initialize()` starts native registration but does not wait for it. `waitForRegistration()` rejects on APNs or Firebase failure, Pushctl API failure, or timeout. `login()` and `logout()` reject when the installation is not registered or the API update fails.

## Initialize options

| Property             | Required           | Description                                      |
| -------------------- | ------------------ | ------------------------------------------------ |
| `applicationKey`     | Yes                | Client token                                     |
| `apiUrl`             | No                 | Defaults to `https://pushctl.com/api/v1`         |
| `appGroupIdentifier` | iOS extension only | Shared App Group for confirmed background events |

## Events

<AccordionGroup>
  <Accordion title="subscriptionRegistered">Emits the confirmed `SubscriptionState` after the Pushctl API registers the native push identifier.</Accordion>
  <Accordion title="registrationFailed">Emits a `message` when native registration, server registration, or the registration wait fails.</Accordion>
  <Accordion title="notificationOpened">Emits `notificationId`, `deliveryId`, title, body, image and action URLs, and string-valued data when the user opens a notification.</Accordion>
  <Accordion title="notificationWillDisplay">Emits the same object before foreground display.</Accordion>
</AccordionGroup>

## Subscription state

| Property             | Type                 | Description                                              |
| -------------------- | -------------------- | -------------------------------------------------------- |
| `installationId`     | `string`             | Stable local installation ID                             |
| `externalUserId`     | `string \| null`     | User associated by the last confirmed login              |
| `permission`         | `PermissionStatus`   | Current native notification permission                   |
| `pushToken`          | `string \| null`     | APNs or Firebase identifier received by the native SDK   |
| `registrationStatus` | `RegistrationStatus` | `unregistered`, `registering`, `registered`, or `failed` |
| `registrationError`  | `string \| null`     | Most recent registration error                           |
| `isRegistered`       | `boolean`            | `true` only after confirmed server registration          |

Permission can be `unknown`, `not_determined`, `authorized`, `provisional`, `ephemeral`, or `denied`. Android commonly uses the first, second, third, and last values.