Quickstart

Get your React Native app connected to Macrofy in under 5 minutes.

Prerequisites

Before you begin, make sure you have:

A Macrofy Dashboard account with an application created (appId + appSecret).
A React Native app using Expo (the SDK works in both Expo Go and development builds).
A backend server capable of computing HMAC-SHA256 signatures.

Install the SDK

Client

pnpm add @macrofy/react-native

Generate a signature

Your backend signs the userId with your appSecret and returns the result to the client. Never include your appSecret in client code.

Your backend

import { createHmac } from 'crypto'

const appId = process.env.MACROFY_APP_ID!
const appSecret = process.env.MACROFY_APP_SECRET!
const signature = createHmac('sha256', appSecret)
  .update(userId)
  .digest('hex')

// Return { appId, userId, signature } to the client

Connect from your app

Pass the payload from your backend into Macrofy.connect(). The SDK validates inputs, exchanges the signature for a JWT, and persists the session automatically via the storage adapter.

React Native

import { Macrofy } from '@macrofy/react-native'

const macrofy = new Macrofy()

const session = await macrofy.connect({
  appId: 'your-app-id',
  userId: 'end-user-id',
  signature: 'hmac-from-your-backend',
})

session.token          // JWT for subsequent API calls
session.user.id        // Macrofy-scoped user ID
session.user.externalId // Your original userId, echoed back

Handle errors

Wrap connect() in a try/catch. Every error is an ApiError with a typed code.

Error handling

import { ApiError, API_ERROR_CODES } from '@macrofy/react-native'

try {
  await macrofy.connect({ appId, userId, signature })
} catch (error) {
  if (error instanceof ApiError) {
    switch (error.code) {
      case API_ERROR_CODES.UNAUTHORIZED:
        // Signature mismatch
        break
      case API_ERROR_CODES.QUOTA_EXCEEDED:
        // Sandbox user limit reached
        break
      case API_ERROR_CODES.NETWORK_ERROR:
        // Device offline
        break
    }
  }
}

Restore session on relaunch

At app startup, call restoreSession(). If a valid session exists in the keychain, you can skip the login flow entirely.

App startup

const session = await macrofy.restoreSession()

if (session) {
  // User is still authenticated — navigate to the main screen
}

To end a session and clear stored credentials:

Disconnect

await macrofy.disconnect()

What's next?

Full authentication guide SDK reference — all methods, types, and exports Error handling reference