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

> Install and initialize the Pushctl Android SDK with Firebase Cloud Messaging.

The Android SDK supports API 23+ and targets Java 17. It uses the Firebase Messaging dependency from the Firebase BOM.

## Prerequisites

* An Android platform with FCM credentials in Pushctl
* A **Client** application token
* Firebase configured for the Android package, including `google-services.json`
* `google()` and `mavenCentral()` in dependency repositories

<Steps>
  <Step title="Add the SDK">
    ```kotlin theme={null}
    dependencies {
        implementation("com.pushctl:pushctl-android:0.3.0")
    }
    ```
  </Step>

  <Step title="Apply Google Services">
    Apply the Google Services Gradle plugin to the app module and place the Firebase `google-services.json` in that module.
  </Step>

  <Step title="Initialize once">
    ```kotlin theme={null}
    class App : Application() {
        override fun onCreate() {
            super.onCreate()
            Pushctl.initialize(this, "push_live_your_client_token")
        }
    }
    ```

    Register this `Application` class in the app manifest if your project does not already use one.
  </Step>

  <Step title="Request permission at the right time">
    ```kotlin theme={null}
    Pushctl.requestPermission(this)
    ```

    Call from an `Activity`. Android 13+ shows the system prompt; earlier versions synchronize the current state.
  </Step>

  <Step title="Wait for confirmed registration">
    ```kotlin theme={null}
    Pushctl.waitForRegistration { error ->
        if (error == null) {
            // Pushctl.subscriptionState().isRegistered is now true.
        } else {
            Log.e("Pushctl", "Registration failed", error)
        }
    }
    ```

    The callback runs after Firebase registration is confirmed by the Pushctl API, or with an error after native failure, API failure, or the default 15-second timeout.
  </Step>
</Steps>

<Info>
  The SDK manifest merges the notification permission, Firebase messaging service, open activity, and dismissal receiver. Do not add a separate `FirebaseMessagingService` for Pushctl.
</Info>

<Warning>Before disabling another notification provider, wait for a successful registration callback. Notification permission or a Firebase identifier alone does not prove that Pushctl has an active installation.</Warning>