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

# iOS SDK

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

## Overview

FlockSDK-iOS enables seamless integration of [Flock](https://www.withflock.com) referral and rewards into your iOS 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
* Navigate within existing web views or create new placements
* Handle events (close, success, invalid) in-app
* Modern Swift builder pattern API for easy configuration
* Officially supported by the Flock team

***

## Requirements

* iOS 14.0 or later
* Swift 5.7 or later
* Xcode 14 or later

***

## Installation

### Swift Package Manager (Recommended)

1. Open your Xcode project.
2. Go to **File > Add Packages...**
3. Enter the repository URL: `https://github.com/Flock-Solutions/FlockSDK-iOS.git`
4. Select a version and add the package to your target.

```swift theme={null}
.package(url: "https://github.com/Flock-Solutions/FlockSDK-iOS.git", from: "1.0.0")
```

***

## Usage

### 1. Configure the SDK

Call `Flock.initialize` once, ideally in your `AppDelegate` or early in your app's startup:

```swift theme={null}
import FlockSDK

Flock.shared.initialize(
    publicAccessKey: "<YOUR_FLOCK_PUBLIC_KEY>",
    environment: .production // or .test
)
```

### 2. Identify Your User

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

```swift theme={null}
Flock.shared.identify(
    externalUserId: "<USER_ID_IN_YOUR_APP>",
    email: "user@example.com",
    name: "Alice Smith",
    customProperties: [
      "tier": .string("Pro"),
      "subscription": .string("annual")
    ]
)
```

### 3. Trigger Checkpoints

Trigger checkpoints to show Flock experiences at specific moments in your user journey. The checkpoint system uses a modern Swift builder pattern for easy configuration.

#### Basic Usage

```swift theme={null}
// Simple checkpoint trigger
Flock.shared.checkpoint("refer_button_clicked").trigger()
```

#### Checkpoint with Callbacks

```swift theme={null}
Flock.shared.checkpoint("refer_button_clicked")
    .onClose {
        print("Checkpoint closed")
    }
    .onSuccess { flock in
        print("Checkpoint succeeded")
    }
    .onInvalid { flock in
        print("Checkpoint invalid")
    }
    .trigger()
```

#### Navigation in Success Callback

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

```swift theme={null}
Flock.shared.checkpoint("user_onboarded")
    .onSuccess { flock in
        // Navigate to success screen when invitee enters valid referral code
        flock.checkpoint("referral_succeeded").navigate().trigger()
    }
    .trigger()
```

#### 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()`: Trigger the checkpoint with configured options

***

## Support

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

***

## License

FlockSDK-iOS is released under the MIT License.