npm package: @klyo/react-native
Description: automated in-app-review
Author: Klyo
Latest version: 0.3.5

# Klyo React Native SDK

A React Native SDK for integrating Klyo's review collection and feedback system into your mobile applications. The
primary focus is to help developers implement in-app review prompts that are strategically timed for maximum user
engagement.

## Key Features

- **Smart Review Prompts**: Show review prompts only when users are most likely to respond positively
- **Automatic User Identification**: Device-based user identification with no additional setup required
- **Review Tracking**: Track when users submit or dismiss reviews
- **Multi-language Support**: English and Arabic support with easy language switching
- **Efficient State Management**: Automatically stops tracking events after a user has taken action

## Installation

```bash
# Install the Klyo SDK
npm install @klyo/react-native

# Install required peer dependencies
npm install @react-native-async-storage/async-storage
npm install react-native-get-random-values
npm install react-native-in-app-review

# For iOS, run pod install
cd ios && pod install && cd ..
```

## Quick Start

Here's the minimum you need to integrate Klyo into your React Native app:

```jsx
import React from 'react';
import { KlyoProvider, KlyoReviewModal } from '@klyo/react-native';

const apiKey = 'YOUR_API_KEY_HERE';

function App() {
  return (
    <KlyoProvider apiKey={apiKey}>
      <YourApp />
      <KlyoReviewModal />
    </KlyoProvider>
  );
}
```

## Usage with Hooks

The SDK provides hooks to easily check eligibility and show reviews:

```jsx
import { useKlyoReview } from '@klyo/react-native';

function ReviewButton() {
  const { isEligible, isLoading, showReview, checkEligibility } =
    useKlyoReview();

  // Check eligibility when component mounts (also auto-checks by default)
  useEffect(() => {
    checkEligibility();
  }, []);

  if (!isEligible) return null;

  return (
    <Button title="Rate our app" onPress={showReview} disabled={isLoading} />
  );
}
```

## User Identification

Klyo SDK automatically handles user identification with a device-specific unique identifier. You don't need to provide
any user data.

The auto-generated device UID is:

- Generated once per device
- Stored in AsyncStorage
- Persisted across app sessions
- Used for all tracking and eligibility checks
- Only cleared when the app is uninstalled or when manually reset

## Event Lifecycle

The SDK follows this core principle: **Once a user has taken an action (submitted or dismissed a review), the SDK stops
initializing** to prevent further tracking and prompting. This ensures users aren't repeatedly asked for reviews after
they've already made a decision.

For developers who need to test the flow, the `regenerateDeviceUID()` method resets this state. This method works even
when the SDK is not initialized, allowing you to reset user state and test review flows any time, regardless of
initialization status.

## Language Support

Klyo supports English and Arabic languages for its review prompts:

```jsx
// Set language at provider level
<KlyoProvider
  apiKey="YOUR_API_KEY_HERE"
  language="ar" // Arabic language
>
  {/* ... */}
</KlyoProvider>
```

Supported languages:

- English (`en`) - default
- Arabic (`ar`)

## Component Props

### KlyoProvider Props

| Prop     | Type    | Required | Default | Description                                     |
| -------- | ------- | -------- | ------- | ----------------------------------------------- |
| apiKey   | string  | Yes      | -       | Your Klyo API key                               |
| debug    | boolean | No       | false   | Enable debug mode                               |
| language | string  | No       | 'en'    | Language code for review content ('en' or 'ar') |

### KlyoReviewModal Props

| Prop                         | Type     | Required | Default   | Description                         |
| ---------------------------- | -------- | -------- | --------- | ----------------------------------- |
| onSuccess                    | function | No       | -         | Callback when review is submitted   |
| onDismiss                    | function | No       | -         | Callback when review is dismissed   |
| successButtonBackgroundColor | string   | No       | '#4A80F0' | Background color for success button |
| customStyles                 | object   | No       | -         | Custom styling for modal components |

#### customStyles Object

| Property          | Type      | Description                 |
| ----------------- | --------- | --------------------------- |
| container         | ViewStyle | Modal container style       |
| modalView         | ViewStyle | Modal content view style    |
| title             | TextStyle | Title text style            |
| description       | TextStyle | Description text style      |
| buttonContainer   | ViewStyle | Container for buttons style |
| successButton     | ViewStyle | Success button style        |
| successButtonText | TextStyle | Success button text style   |
| dismissButton     | ViewStyle | Dismiss button style        |
| dismissButtonText | TextStyle | Dismiss button text style   |
| loadingIndicator  | ViewStyle | Loading indicator style     |

## API Reference

### Klyo Singleton

| Method                | Parameters                                    | Return          | Description                                                                                         |
| --------------------- | --------------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------- |
| `init`                | apiKey: string, options?: { debug?: boolean } | Promise<void>   | Initializes the SDK (called automatically by KlyoProvider)                                          |
| `setDebugMode`        | enabled: boolean                              | void            | Enables/disables debug mode                                                                         |
| `isDebugModeEnabled`  | -                                             | boolean         | Returns current debug mode status                                                                   |
| `setLanguage`         | language: 'en' \| 'ar'                        | void            | Sets the language for review content                                                                |
| `getLanguage`         | -                                             | 'en' \| 'ar'    | Gets the current language setting                                                                   |
| `regenerateDeviceUID` | -                                             | Promise<string> | Resets the device UID and user action status (for testing) - works even when SDK is not initialized |
| `isInitialized`       | -                                             | boolean         | Checks if the SDK has been initialized                                                              |

### KlyoContext (useKlyo hook)

| Property         | Type                   | Description                                 |
| ---------------- | ---------------------- | ------------------------------------------- |
| isInitialized    | boolean                | Whether the SDK has been initialized        |
| isUserSet        | boolean                | Whether a user ID has been set              |
| userId           | string                 | The current user ID (auto-generated)        |
| hasReviewed      | boolean                | Whether the user has already reviewed       |
| error            | string \| null         | Any error encountered during initialization |
| language         | 'en' \| 'ar'           | The current language setting                |
| checkEligibility | () => Promise<boolean> | Check if user is eligible for a review      |

### useKlyoReview Hook

| Property         | Type                   | Description                                      |
| ---------------- | ---------------------- | ------------------------------------------------ |
| isEligible       | boolean                | Whether the user is eligible to show a review    |
| isLoading        | boolean                | Whether an eligibility check is in progress      |
| error            | string \| null         | Any error that occurred during eligibility check |
| config           | object \| null         | Review configuration from the server             |
| checkEligibility | () => Promise<void>    | Check if the user is eligible for a review       |
| showReview       | () => Promise<boolean> | Show the review dialog                           |
| dismissReview    | () => Promise<void>    | Dismiss the review without showing               |

## Example

Check out the `example` directory for a complete working example.

## License

MIT