# PERS SDK React Native Introduction

The PERS React Native SDK provides authentication, token, campaign, and redemption operations for React Native apps, with native passkey (WebAuthn) support and on-device blockchain transaction signing. It wraps the same Manager-Service architecture as `@explorins/pers-sdk`, exposed through React hooks and a context provider.

## What is PERS?

PERS is a SaaS tokenization and loyalty infrastructure. The React Native SDK provides access to:

- **Authentication** - Passkey (WebAuthn) login with device biometrics, secure token storage
- **Token Operations** - Balance queries, transfers, on-chain reads
- **Campaign Management** - Campaign discovery, claims, triggers
- **Redemptions** - Reward redemption with automatic blockchain signing when required
- **Business Operations** - Merchant and partner integrations
- **Transaction Signing** - Native ECDSA signing via `react-native-quick-crypto`


## Installation

```bash
npm install @explorins/pers-sdk-react-native
npm install @react-native-async-storage/async-storage
```

> Native dependencies (`react-native-quick-crypto`, `react-native-keychain`, `react-native-passkey`) install automatically but require a native rebuild (`npx expo run:android` / `pod install`). Metro must have `unstable_enablePackageExports = true` — see the package README for full setup and Android New Architecture requirements.


## Quick Start

### 1. Set up the Provider

```typescript
import React from 'react';
import { PersSDKProvider } from '@explorins/pers-sdk-react-native';

export default function App() {
  return (
    <PersSDKProvider config={{
      apiUrl: 'https://api.pers.ninja',
      tenantId: 'your-tenant-id' // Optional
    }}>
      <NavigationContainer>
        <YourAppContent />
      </NavigationContainer>
    </PersSDKProvider>
  );
}
```

### 2. Authentication & Token Operations

```typescript
import { useAuth, useTokens, useRedemptions, useTransactionSigner } from '@explorins/pers-sdk-react-native';

function RewardScreen() {
  const { user, isAuthenticated, login } = useAuth();
  const { getTokens } = useTokens();
  const { redeem } = useRedemptions();

  if (!isAuthenticated) return <LoginScreen onLogin={login} />;

  return <YourRewardUI user={user} onRedeem={redeem} />;
}
```

## Architecture Overview

Same Manager-Service pattern as the core SDK, exposed via hooks:

- **useAuth** - Authentication and user sessions
- **useUsers** - User profile management
- **useTokens** / **useTokenBalances** - Token operations and on-chain balances
- **useCampaigns** - Marketing campaigns
- **useRedemptions** - Reward redemptions
- **useTransactions** - Transaction history
- **usePurchases** - Purchase and payment processing
- **useTriggerSources** - Campaign trigger sources
- **useWeb3** - Blockchain operations
- **useTransactionSigner** - Native transaction signing (passkey-backed)


## Critical Setup: Passkeys

To enable Passkey authentication (WebAuthn) on iOS and Android, register your app with the PERS backend (contact **support@explorins.com** with your Bundle ID/Apple Team ID or Package Name/SHA-256 fingerprint) and configure native files per the Passkey Setup Guide. Use development builds with Expo, not Expo Go.

## Related Packages

- **[@explorins/pers-sdk](https://www.npmjs.com/package/@explorins/pers-sdk)** - Platform-agnostic core SDK. Use this for web/Node.js instead of this package.
- **[@explorins/pers-shared](https://www.npmjs.com/package/@explorins/pers-shared)** - Shared types, interfaces, and DTOs used across the PERS ecosystem (required peer dependency)


## Support and Resources

- **Package**: [npm package](https://www.npmjs.com/package/@explorins/pers-sdk-react-native)
- **Platform Documentation**: [PERS Platform Docs](https://docs.pers.ninja/1.intro)
- **Support**: Contact support@explorins.com for issues and feature requests


## License

MIT License - See package for full license details.