Mobile SDK breadcrumbs

Breadcrumbs are lightweight diagnostic events emitted as the Privy SDK progresses through key flows, such as session restoration and wallet creation. Register a breadcrumb handler to receive these events and forward them to your own analytics, logging, or observability tooling (e.g. Sentry, Datadog, Firebase).

Breadcrumbs are currently available on the Privy iOS and Android native SDKs only.

Breadcrumbs are for lightweight operational visibility, not full error reporting. Payloads never contain PII, and handlers must not throw or block, since they’re called synchronously on the emitting thread.

Implement the platform’s breadcrumb handler interface and pass it to your PrivyConfig when initializing the SDK.

import PrivySDK

struct LoggingBreadcrumbHandler: PrivyBreadcrumbHandler {
    func receive(_ breadcrumb: PrivyBreadcrumb) {
        print("PrivyBreadcrumb: \(breadcrumb.event) timestamp=\(breadcrumb.timestamp) data=\(breadcrumb.data)")
        // Forward to your analytics or observability tool, e.g.:
        // Analytics.track(breadcrumb.event, properties: breadcrumb.data)
    }
}

let config = PrivyConfig(
    appId: privyAppId,
    appClientId: privyAppClientId,
    breadcrumbHandler: LoggingBreadcrumbHandler()
)

breadcrumbHandler is optional. If it’s omitted, the SDK emits no breadcrumbs and there’s no performance cost. Every breadcrumb exposes the same three fields, regardless of event type:

Field	Type	Description
`event`	`String`	Dotted event name, e.g. `auth.session_restore.started`
`timestamp`	`Date` (iOS) / `Long` epoch millis (Android)	The time the event occurred
`data`	`[String: String]` (iOS) / `Map<String, String>` (Android)	Additional context for the event. Values are strings only

receive(_:) is called synchronously on the thread that triggered the event. Keep handler implementations fast and non-blocking, and dispatch any expensive work (network calls, disk writes) to a background queue.

Show Session restore events

Emitted when the SDK attempts to restore a cached session on startup.

Event	When it fires
`auth.session_restore.started`	A prior session was found and restoration has begun
`auth.session_restore.completed`	The session was successfully refreshed and restored
`auth.session_restore.failed`	Restoration failed; `data.error` describes the failure

Show Wallet events

Emitted for embedded wallet creation, migration, and bridge operations.

Event	When it fires
`wallet.create.started`	Embedded wallet creation began; `data.chain-type` is `ethereum` or `solana`
`wallet.create.completed`	Embedded wallet creation succeeded
`wallet.create.failed`	Embedded wallet creation failed; `data.error` describes the failure
`wallet.migration.started`	Migration of legacy embedded wallets to the TEE stack began
`wallet.migration.completed`	Migration completed successfully
`wallet.migration.failed`	Migration failed; `data.error` describes the failure
`wallet.bridge.failed`	The webview/iframe bridge failed to complete an operation (timeout or transport error), as opposed to the operation being rejected by the server

On iOS, data.error is a stable, non-sensitive error code (the PrivyError code hierarchy, or just the Swift type name for non-PrivyError types). On Android, data.error is currently the underlying exception’s message. Avoid logging Android data.error values to systems where raw exception messages shouldn’t be stored, and treat both as best-effort diagnostic strings rather than a stable enum.

4. Example: forwarding to Sentry

import Sentry

struct SentryBreadcrumbHandler: PrivyBreadcrumbHandler {
    func receive(_ breadcrumb: PrivyBreadcrumb) {
        let crumb = Breadcrumb(level: .info, category: "privy")
        crumb.message = breadcrumb.event
        crumb.data = breadcrumb.data
        SentrySDK.addBreadcrumb(crumb)
    }
}

Because breadcrumbs carry no PII and are cheap to emit, it’s safe to register a handler in every build configuration, including production. Gate any verbose console logging (like the examples in step 1) behind a debug flag.

​1. Register a breadcrumb handler

​2. Breadcrumb payload shape

​3. Available breadcrumb events

​4. Example: forwarding to Sentry

1. Register a breadcrumb handler

2. Breadcrumb payload shape

3. Available breadcrumb events

4. Example: forwarding to Sentry