Skip to content
Last updated

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

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

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

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.

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

Support and Resources

License

MIT License - See package for full license details.