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

# Android SDK

> Integrate Flock’s referral and rewards platform into your Android app with the official FlockSDK. This guide covers setup, configuration, and usage for Kotlin-based Android apps.

## Overview

FlockSDK-Android enables seamless integration of [Flock](https://www.withflock.com) referral and rewards into your Android applications. Effortlessly build powerful referral programs and track customer engagement in minutes.

* Identify and track users
* Trigger checkpoints to show Flock experiences at specific moments in your user journey
* Officially supported by the Flock team

***

## Requirements

* Android 6.0 (API 23) or later
* Kotlin 1.7 or later
* Android Gradle Plugin 7.0 or later

***

## Installation

### Gradle (Recommended)

1. Add the SDK to your `build.gradle` dependencies:

```groovy theme={null}
implementation 'com.withflock:flocksdk:YOUR_VERSION'
```

2. Replace `YOUR_VERSION` with the latest version from [Jitpack](https://jitpack.io/#Flock-Solutions/FlockSDK-Android).

***

## Usage

### 1. Configure the SDK

Call `FlockSDK.initialize` once, ideally in your `Application` class or early in your app's startup:

```kotlin theme={null}
FlockSDK.initialize(
    publicAccessKey = "<YOUR_FLOCK_PUBLIC_KEY>",
    environment = FlockEnvironment.PRODUCTION // or FlockEnvironment.TEST
)
```

### 2. Identify Your User

Identify the current user (after login or at app start):

```kotlin theme={null}
CoroutineScope(Dispatchers.Main).launch {
    FlockSDK.identify(
        externalUserId = "<USER_ID_IN_YOUR_APP>",
        email = "user@example.com",
        name = "Alice Smith",
        customProperties = mapOf(
            "tier" to "pro",
            "subscription" to "annual"
        )
    )
}
```

### 3. Trigger Checkpoints

Trigger checkpoints to show Flock experiences at specific moments in your user journey.

#### Basic Usage

```kotlin theme={null}
// Simple checkpoint trigger
FlockSDK.checkpoint("refer_button_clicked").trigger(context)
```

#### Checkpoint with Callbacks

```kotlin theme={null}
FlockSDK.checkpoint("refer_button_clicked")
    .onClose {
        println("Checkpoint closed")
    }
    .onSuccess {
        println("Checkpoint succeeded")
    }
    .onInvalid {
        println("Checkpoint invalid")
    }
    .trigger(context)
```

#### Navigation in Success Callback

Use navigation within success callbacks to show success screens after successful actions:

```kotlin theme={null}
FlockSDK.checkpoint("user_onboarded")
    .onSuccess {
        // Navigate to success screen when invitee enters valid referral code
        FlockSDK.checkpoint("referral_succeeded").navigate().trigger(context)
    }
    .trigger(context)
```

#### Checkpoint Options

<Callout type="info">
  The checkpoint system automatically loads campaign checkpoints when you call `identify()`. Make sure to call `identify()` before triggering any checkpoints.
</Callout>

**Available Methods:**

* `navigate()`: Navigate within existing web view instead of creating a new placement
* `onClose()`: Handle when the checkpoint is closed
* `onSuccess()`: Handle successful checkpoint completion
* `onInvalid()`: Handle invalid checkpoint events
* `trigger(context)`: Trigger the checkpoint with configured options (requires Android context)

***

## Why Flock?

* No UI to build – We handle the referral screens for you.
* Fully managed backend and analytics.
* Easy integration and customization.
* Official support and regular updates.

***

## Support

* [Open an issue](https://github.com/Flock-Solutions/FlockSDK-Android/issues) on GitHub
* Email: [support@withflock.com](mailto:support@withflock.com)

***

## License

FlockSDK-Android is released under the MIT License.

***