PERS SDK - v2.3.26 / Exports / PersConfig

PERS SDK Configuration

Example

// Production setup
const config: PersConfig = {
  environment: 'production',
  apiProjectKey: 'your-project-key',
};

// Custom API URL (for development/testing)
const devConfig: PersConfig = {
  customApiUrl: 'https://my-local-api.ngrok.io/v2',
  apiProjectKey: 'your-project-key',
};

• environment
• customApiUrl
• apiProjectKey
• apiVersion
• timeout
• retries
• authType
• authStorage
• dpop
• authProvider
• tokenRefreshMargin
• backgroundRefreshThreshold
• captureWalletEvents
• walletEventsWsUrl
• autoRestoreSession
• dataSource
• platform
• apiRoot

• Optional environment: PersEnvironment

Target environment - 'staging' or 'production' (default: 'production')

core/pers-config.ts:40

• Optional customApiUrl: string

Custom API URL - overrides environment setting. Use this for local development or custom deployments.

core/pers-config.ts:46

• Optional apiProjectKey: string

Project key for API authentication

core/pers-config.ts:49

• Optional apiVersion: "v2"

API version to use (default: 'v2')

core/pers-config.ts:52

• Optional timeout: number

Request timeout in milliseconds (default: 30000)

core/pers-config.ts:55

• Optional retries: number

Number of retry attempts (default: 3)

core/pers-config.ts:58

• Optional authType: AccountOwnerType

Authentication type for auto-created provider (default: AccountOwnerType.USER)

core/pers-config.ts:61

• Optional authStorage: TokenStorage

Custom token storage for auto-created provider

Recommendation

Use new IndexedDBTokenStorage() for better security/performance

core/pers-config.ts:68

• Optional dpop: Object

DPoP (Demonstrating Proof-of-Possession) Configuration for auto-created provider

core/pers-config.ts:71

• Optional authProvider: PersAuthProvider

Authentication provider instance (overrides authType if provided)

core/pers-config.ts:79

• Optional tokenRefreshMargin: number

Seconds before expiry to refresh token proactively (default: 60)

core/pers-config.ts:82

• Optional backgroundRefreshThreshold: number

Seconds threshold for background vs blocking refresh (default: 30)

core/pers-config.ts:85

• Optional captureWalletEvents: boolean

Enable real-time wallet events (default: true)

When enabled, SDK auto-connects to wallet events after authentication. Events are streamed through sdk.events and sdk.walletEvents.

core/pers-config.ts:97

• Optional walletEventsWsUrl: string

Custom wallet events WebSocket URL - overrides environment default. Default: wss://events.pers.ninja (production) or wss://dev.events.pers.ninja (staging)

core/pers-config.ts:103

• Optional autoRestoreSession: boolean

Automatically restore session from stored tokens on SDK initialization (default: true)

When enabled, SDK checks for valid stored tokens during construction and automatically restores the user session. This eliminates the need to manually call restoreSession() and prevents "logged out" flash on app start.

The restoration runs asynchronously and emits 'session_restored' event on success.

Set to false if you need manual control over session restoration timing.

core/pers-config.ts:120

• Optional dataSource: DataSource

Default data source for analytics tracking.

Sets tracking headers on all API requests for attribution:

• x-source-channel: Primary ingestion channel (web, mobile, api, etc.)
• x-source-medium: Marketing medium (email, referral, organic, etc.)
• x-source-campaign: Campaign identifier for tracking
• x-source: Traffic source reference

Example

// Simple channel tracking
const config: PersConfig = {
  dataSource: { channel: 'mobile' }
};

// Full attribution tracking
const config: PersConfig = {
  dataSource: {
    channel: 'web',
    medium: 'email',
    campaign: 'summer_promo_2026',
    source: 'mailchimp'
  }
};

core/pers-config.ts:153

• Optional platform: Platform

Platform information for analytics.

Sent as JSON in x-platform header for device/browser analytics:

• Native: os, osVersion, app, appVersion, deviceType
• Web: os, browser, browserVersion, deviceType

Example

// Native app
const config: PersConfig = {
  platform: {
    os: 'iOS',
    osVersion: '17.4',
    app: 'MyApp',
    appVersion: '2.3.1',
    deviceType: 'phone'
  }
};

core/pers-config.ts:176

• Optional Readonly apiRoot: string

Internal - API root URL constructed automatically

core/pers-config.ts:179