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

# Android SDK reference

> Reference Android initialization options, methods, models, and notification listeners.

## Configuration

```kotlin theme={null}
Pushctl.initialize(
    context,
    PushctlConfiguration(
        applicationKey = "push_live_your_client_token",
        apiUrl = "https://pushctl.com/api/v1",
        notificationChannelId = "orders",
        notificationChannelName = "Order updates",
        notificationIcon = R.drawable.ic_notification,
    ),
)
```

| Option                    | Default                      | Description                                         |
| ------------------------- | ---------------------------- | --------------------------------------------------- |
| `applicationKey`          | Required                     | Client token for the application                    |
| `apiUrl`                  | `https://pushctl.com/api/v1` | Override only for self-hosting or local development |
| `notificationChannelId`   | `pushctl_default`            | Android notification channel ID                     |
| `notificationChannelName` | `Notifications`              | User-visible channel name                           |
| `notificationIcon`        | App icon                     | Drawable resource for notifications                 |

## Methods

| Method                                         | Purpose                                                                |
| ---------------------------------------------- | ---------------------------------------------------------------------- |
| `initialize(context, key, apiUrl)`             | Initialize with basic options                                          |
| `initialize(context, configuration)`           | Initialize with channel and icon options                               |
| `requestPermission(activity)`                  | Request or synchronize notification permission                         |
| `syncPermission()`                             | Send the current permission state                                      |
| `waitForRegistration(timeoutMillis, callback)` | Wait for confirmed registration; defaults to 15 seconds                |
| `login(externalUserId, callback)`              | Associate this installation with a user and report the API result      |
| `logout(callback)`                             | Remove its current user association and report the API result          |
| `subscriptionState()`                          | Read installation, identity, permission, token, and registration state |
| `addRegistrationListener`                      | Observe confirmed registration and failures                            |
| `removeRegistrationListener`                   | Stop observing registration changes                                    |
| `addNotificationClickListener`                 | Observe notification opens                                             |
| `addForegroundNotificationListener`            | Observe a push received while foregrounded                             |
| `handleNotificationOpen(intent)`               | Process an open intent in custom integrations                          |

`PushctlOperationCallback` receives `null` on success or a `Throwable` on failure. 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`. Implement `PushctlRegistrationListener` to receive `onRegistered(state)` and `onRegistrationFailed(error)` callbacks.

<Expandable title="Notification model">
  `PushctlNotification` contains `notificationId`, `deliveryId`, optional `title`, `body`, `imageUrl`, and `actionUrl`, plus `data: Map<String, String>`.
</Expandable>