LucraClient Initialization (iOS)

This document describes how to properly create and initialize the LucraClient on iOS, manage authentication, and keep user state in sync with Lucra.

---

Overview

The LucraClient is the primary entry point into the Lucra iOS SDK. It is responsible for:

• Managing the authenticated Lucra user

• Coordinating presentation of Lucra UI flows (LucraFlow)

• Exposing headless APIs (lucraClient.api.*)

• Publishing user and event updates to your app

---

Creating the Client

Create a shared instance early in the app lifecycle:

• NOTE: Please be sure that the model object that references the LucraSDK for your application is available in a @MainActor context. This ensures business logic will be processed in a thread safe manner and your UI will update accordingly.

import LucraSDK

@MainActor
final class LucraSharedEnvironment: ObservableObject {
    @Published var lucraClient: LucraClient

    init(apiKey: String, environment: LucraEnvironment, urlScheme: String, merchantID: String?, appearance: ClientTheme) {
        lucraClient = .init(config: .init(environment: .init(apiKey: apiKey,
                                                             environment: environment,
                                                             urlScheme: urlScheme,
                                                             merchantID: merchantID),
                                          appearance: appearance))
    }
}

Use .sandbox during integration and testing.

---

Authenticating Users

Lucra supports two major authentication paths:

1. Lucra-hosted onboarding

Lucra manages login and KYC within its own UI.

2. Your authentication → Lucra identity linkage

Your app authenticates the user, then provides Lucra with their identifying info using the configure method.

Example:

Configure User Properties

Description: Pushes profile attributes into Lucra for the currently authenticated user. Only non-null values on the supplied SDKUser are submitted.

If configure is invoked before the Lucra session is established, the request is queued and automatically retried after login. Deprecated properties such as birthday are ignored. Any values sent here are also surfaced inside LucraFlow.VerifyIdentity, minimizing what the user must re-enter during KYC.

Phone number implications

• Provide phoneNumber only when you intend to bind the Lucra account to that value. After the number is verified, the SDK login flow requires the same phone for future authentications.

• Skip the field (or pass null) if you prefer Lucra to collect and manage the phone number directly.

• Whatever value you send appears pre-filled in the Verify Identity flow.

User metadata implications

• Use metadata to pass identifiers and traits from your system. This is a Map of Strings to Strings (["":""]), an external_id entry (example: "external_id":"your_custom_user_id") is recommended at minimum to bind your users to Lucra users as that's what Lucra's backend will prioritize. This will help for score submission and other identifying properties from Lucra systems.

func configure(client: LucraClient, currentUser: YourUser) async {
    do {
        try await client.configure(
            user: .init(
                username: currentUser.username,
                avatarURL: currentUser.avatarURL,
                phoneNumber: currentUser.phone,
                email: currentUser.email,
                firstName: currentUser.firstName,
                lastName: currentUser.lastName,
                metadata: currentUser.metadata,
                address: .init(
                    address: currentUser.address1,
                    addressCont: currentUser.address2,
                    city: currentUser.city,
                    state: currentUser.state,
                    zip: currentUser.zip
                ),
                dateOfBirth: currentUser.dateOfBirth
            )
        )
    } catch {
        print("Lucra configure failed: \(error)")
    }
}

⚠️ Updating user info like first name, last name, city may trigger re-verification depending on compliance rules.

---

Listening for User Updates

The SDK publishes user updates:

import Combine

final class LucraUserObserver: ObservableObject {
    @Published var user: LucraUser?
    private var cancellable: AnyCancellable?

    init(client: LucraClient) {
        cancellable = client.$user.sink { [weak self] newUser in
            self?.user = newUser
        }
    }
}

Use this to sync changes to your UI or backend.

---

Logging Out

func logoutLucra(_ client: LucraClient) {
    client.logout()
}

This clears all Lucra identity and session data.

---

Next Steps

Once initialized, proceed to:

Lucra Flows - Full screen UI experiences

Lucra Flows

Headless APIs - Programmatic matchup creation & data fetching

Headless APIs

Deeplinks - Routing users into Matchups

Deeplinks

Push Notifications - Handling Lucra-triggered events

Push Notifications

See the corresponding docs for deeper integration.