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

# React Native SDK

> Integrate Flock’s referral and rewards platform into your React Native app with the official Flock SDK. This guide covers setup, configuration, and usage for React Native apps.

## Overview

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

* Identify and track users
* Present referral experiences as modals or full screen
* Handle events (close, success, invalid) in-app
* Officially supported by the Flock team

***

## Requirements

* React Native 0.60 or later (auto-linking supported)
* iOS 13.0 or later (if targeting iOS)
* Android 6.0 (API 23) or later (if targeting Android)
* Node.js 14 or later

***

## Installation

### 1. Install the Package

```bash theme={null}
npm install @wflock/react-native-sdk
```

OR

```bash theme={null}
yarn add @wflock/react-native-sdk
```

### 2. Link the Native Dependencies

Auto-linking handles native dependencies for React Native 0.60+.

#### For iOS

1. Install CocoaPods dependencies:

```bash theme={null}
cd ios && pod install
```

2. Ensure your `Info.plist` file includes permissions for internet access:

```xml theme={null}
<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>
```

#### For Android

Make sure `AndroidManifest.xml` includes the following permission:

```xml theme={null}
<uses-permission android:name="android.permission.INTERNET" />
```

***

## Usage

### 1. Configure the SDK

Wrap your app in the `FlockSDKProvider` and pass the `publicAccessKey` and `environment`:

```tsx theme={null}
import React from 'react';
import { FlockSDKProvider } from '@wflock/react-native-sdk';
import App from './App';

const Main = () => (
  <FlockSDKProvider publicAccessKey="<YOUR_FLOCK_PUBLIC_KEY>" environment="production">
    <App />
  </FlockSDKProvider>
);

export default Main;
```

### 2. Identify Your User

Call `identify` after your user logs in to link their identity with Flock:

```tsx theme={null}
import { useFlockSDK } from '@wflock/react-native-sdk';

const handleLoginSuccess = async (user) => {
  const { identify } = useFlockSDK();
  await identify({
    externalUserId: user.id,
    email: user.email,
    name: user.name,
  });
};
```

### 3. Show a Flock Page

#### Placement API (Recommended)

> **New:** Use `addPlacement(placementId, options)` to display a referral component. Each campaign page now has a unique `placementId` for robust and future-proof integration.

A placement renders a Flock referral page within your app, making it easy to prompt users to share and participate in your referral program.

```tsx theme={null}
import { useFlockSDK } from '@wflock/react-native-sdk';
import { Button } from 'react-native';

const ReferralButton = () => {
  const { addPlacement } = useFlockSDK();
  return (
    <Button
      title="Show Referral"
      onPress={() => addPlacement('referrer', {
        onClose: () => console.log('Modal closed'),
        onSuccess: () => console.log('Referral sent!'),
        onInvalid: () => console.log('Invalid referral'),
        showCloseButton: true,
      })}
    />
  );
};
```

* The legacy `openPage(type, options)` method is now **deprecated** and will be removed in a future release.
* Use the Placement API for all new integrations and update any usage of `openPage` to `addPlacement`.

#### Invitee Placement

To display the invitation page for the invitee, use the `addPlacement` method with the `invitee` placement ID:

```tsx theme={null}
import { useFlockSDK } from '@wflock/react-native-sdk';
import { Button } from 'react-native';

const InviteeButton = () => {
  const { addPlacement } = useFlockSDK();
  return (
    <Button
      title="Open Invitee Page"
      onPress={() => addPlacement('invitee', {
        onSuccess: () => console.log('Invitee entered valid referral code'),
        onInvalid: () => console.log('Invitee entered invalid referral code'),
        onClose: () => console.log('Modal closed'),
      })}
    />
  );
};
```

#### Legacy API (Deprecated)

> **Deprecated:** `openPage(type, options)` is now deprecated. Use `addPlacement(placementId, options)` for all new integrations.

```tsx theme={null}
import { useFlockSDK } from '@wflock/react-native-sdk';

const { openPage } = useFlockSDK();
openPage('referrer', {
  onClose: () => console.log('WebView closed'),
});
```

***

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

***

## FAQ

**Q: What React Native version is required?**
A: @wflock/react-native-sdk supports React Native 0.60 and above.

**Q: Can I customize WebView actions?**
A: Yes, you can listen to messages from the WebView and define custom follow-up actions.

**Q: Where can I get support?**
A: Contact the Flock support team at [support@withflock.com](mailto:support@withflock.com).

***

Thank you for using Flock SDK!