Skip to main content

Quick Start

This page walks the whole path: configure the SDK, sign a user in, find one of their avatars, render it, dress it, and talk to it.

Before writing any of it, it's worth opening genies-sdk-sandbox-ios — a complete app that does everything on this page. It's a private repository, so ask Genies for access if you don't have it, and it builds on the package setup from Installation. Seeing the calls in a project that already builds makes the rest of this page easier to place.

Steps 1–3 use the Auth and Inventory modules; steps 4–6 use GeniesPartnerSDKNAF, which bridges them to NAF. See the Partner SDK API, the Partner SDK NAF API, or the NAF API for direct rendering control.

1. Configure and sign in​

Configure once at launch, before any other call. Genies issues you an app ID; the environment supplies the hosts.

The simplest path is to let the auth client configure the core runtime for you in a single call. configure throws, so handle it where you call it — at app launch there's nowhere above you to catch it:

import SwiftUI
import GeniesPartnerSDK

@main
struct MyApp: App {
private let appID = "<the app ID Genies issued you>"
private let auth = GeniesAuthClient()

init() {
do {
try auth.configure(environment: .production, appName: "YourApp", appID: appID)
} catch {
print("Genies configure failed: \(error)")
}
}

var body: some Scene {
WindowGroup { ContentView() }
}
}

An app ID on its own is everything magic-link sign-in needs. A client ID is only required for federated sign-in — see Signing in another way.

note

If you'd rather bring the core runtime up first — to start notifications early, say — call GeniesSDK.configure(core:) and then the no-argument auth.configure() to attach. Don't do both: a value-carrying auth.configure(...) after GeniesSDK.configure(core:) fails with "GeniesSDK core is already configured."

Everything after this throws, the NAF calls are async, and NAF's view and chat types are main-actor isolated. The snippets below assume they sit inside a method that carries all three, with auth the client you configured above:

@MainActor
func startSession() async throws {
// steps 2–6 go here
}

2. Sign the user in​

Magic link is the recommended flow: Genies sends a one-time code to an email address or phone number, and you verify it.

let start = try auth.startMagicLink(email: email)
// Genies sends the code. `start.expiresAt` says how long it's good for.

// Collect the code from the user, then:
let result = try auth.verifyMagicLink(email: email, code: code)
// Session is established; Inventory calls can now be made.

startMagicLink(phoneNumber:) and verifyMagicLink(phoneNumber:code:) do the same over SMS — the number must be E.164, country code included and no separators, like +12345678901. verifyMagicLink(code:) works when a start call is already pending. Sessions refresh with refreshConsumerSession().

3. Find an avatar​

The Inventory module returns identifiers and display data — names and icons for building a picker — not models or textures.

Start from the catalog. It's the published set, so it has something to show before the user owns anything:

let inventory = GeniesInventoryClient()

let page = try inventory.listCatalogAvatars(
kind: .smartAvatar, // .all or .avatar for looks that don't chat
ownership: .all, // .owned / .notOwned to split the two
free: nil,
limit: 50,
cursor: nil
)

// Build your picker from `name`; each row carries `owned`, `free`, and `canChat`.
guard let selected = page.items.first else { return }
let ref = selected.ref

Pass page.nextCursor back as cursor for the next page; it's nil on the last one. listCatalogWearables(categories:ownership:free:limit:cursor:) browses wearables the same way.

For what the user already owns, listOwnedAvatars(kind:) and listOwnedWearables() return their items unpaginated.

Use getAvatar(ref:) for the shared catalog view of an avatar, or getUserAvatar(ref:) for the signed-in user's personalized view.

4. Render it with NAF​

Add GeniesPartnerSDKNAF and hand NAFView the reference from step 3 directly.

import GeniesPartnerSDKNAF
import NAFKitUI

let view = try NAFView()
containerView.addSubview(view) // your own view; give it a frame or constraints

try await view.loadUserAvatar(ref) // with the user's saved outfit
// or: try await view.loadAvatar(ref) for the avatar as published

view.frameAvatar() // camera framing

loadUserAvatar renders what the user saved; loadAvatar renders the avatar as published. Both take silhouette: to show a low-detail stand-in while the full avatar streams in, and lods: for the LOD progression. Both also apply the avatar's authored toon shading for you — going through NAF directly, you'd apply a preset yourself.

5. Dress it, and save what they picked​

The same extensions take wearables straight from the Inventory module:

let wearables = try inventory.listOwnedWearables()
guard let hat = wearables.first else { return }

try await view.equip(hat) // NAF replaces whatever it displaces
try await view.unequip(hat)

try await view.saveOutfit(to: ref) // what's worn is what saves

6. Talk to it​

If the avatar is a smart avatar (canChat is true), you can hold a conversation. Create the chat after the avatar has loaded:

let chat = try GeniesChat(avatar: ref, view: view)

var transcript = ""
let turn = chat.send("Hey, what are you up to?")
for await text in turn.reply {
transcript += text.displayText
}

NAF performs the reply on the avatar and the SDK plays the voice. GeniesChat is an ObservableObject, so SwiftUI can drive your UI off state, which moves between .idle, .listening, .thinking, and .speaking.

See the Partner SDK NAF API for text, voice, and live modes, push-to-talk, sessions, and history.

Signing in another way​

Magic link covers most integrations with nothing but an app ID. If you need federated sign-in — the browser-based PKCE flow against an identity provider — ask Genies for a client ID as well, and configure with an overload that carries both. It replaces the configure call in step 1, inside the same do / catch:

try auth.configure(environment: .production, appName: "YourApp",
clientID: clientID, appID: appID)

auth.signIn(
redirectURL: redirectURL,
scope: scope,
presentationContextProvider: self
) { result in
// Session is established.
}

redirectURL must be a Universal Link your app has registered, never a custom scheme. Without a client ID, signIn fails with "A federated client_id must be configured before signIn".

See the Partner SDK API for silent sign-in, callback handling, and cancellation.

Going direct: bringing your own renderer​

The conveniences above keep the Partner SDK and NAF easy to follow. When you want more direct control — over loading, composition, or the render loop — work against NAF itself.

This runs on the main actor too — NAFAvatarSession and the NAFAvatarRenderer you write are both main-actor isolated.

If you own the Metal pipeline, use NAFAvatarSession instead of NAFView. The SDK still owns asset loading, animation, behavior, and per-frame skeleton math; you own the scene and camera. onMeshesRebuilt fires after every composition change — load, equip/unequip, LOD upgrade, silhouette swap — and your renderer replaces its submesh set.

import NAFKit
import NAFKitUI
import NAFKitUITools

let metalRenderer = NAFRenderer(device: nil)
let session = NAFAvatarSession(device: metalRenderer.device)

let myRenderer = MyMetalRenderer(device: metalRenderer.device) // conforms to NAFAvatarRenderer

session.onMeshesRebuilt = { [weak myRenderer] meshes in
myRenderer?.applyMeshes(meshes)
}

// Gaze hooks — set once; `tick(...)` reads them per frame.
session.cameraPositionProvider = { [weak cam] in cam?.eyePosition ?? .zero }
session.avatarModelTransform = uprightTransform

// Takes the id from the ref, rather than the ref itself.
guard let smartAvatarID = ref.smartAvatarID else { return }
try await session.loadCampSmartAvatar(smartAvatarID, silhouette: true, lods: [2, 0])

metalRenderer.onUpdate = { [weak session, weak myRenderer] dt in
if let session, let myRenderer {
session.tick(deltaTime: Float(dt), renderer: myRenderer)
}
}

metalRenderer.onRender = { [weak myRenderer] encoder in
let frame = FrameContext(view: viewMatrix, viewProjection: viewProjection, aspect: aspect)
myRenderer?.render(encoder: encoder, context: frame)
}

Next steps​