Partner SDK API
The Genies Partner SDK gives you three modules. Each is a client you instantiate; all three arrive in one import, GeniesPartnerSDK. Rendering is NAF's job — see the NAF API.
| Module | Entry point | Covers |
|---|---|---|
| (shared runtime) | GeniesSDK | Configuration and lifecycle |
| Auth | GeniesAuthClient | Sign-in, sessions, tokens |
| Inventory | GeniesInventoryClient | Ownership, entitlements, avatars, catalog |
| Notifications | GeniesNotificationsClient | Live inventory events |
Every client is Objective-C backed, so each call that can fail takes an NSError out-parameter and surfaces in Swift as a throws method.
Configuration and lifecycle
Configure the SDK once at launch, before any other call.
GeniesSDK
| API | Purpose |
|---|---|
configure(core:) | Configure the shared runtime from a GeniesCoreConfiguration. Throws on failure. |
isConfigured | Whether configuration has completed. |
observeCredentialState(_:) | Observe session credential changes with a GeniesCredentialStateHandler. Returns a GeniesCredentialObservation. |
shutdown() | Tear down the shared runtime. |
GeniesCoreConfiguration
Four initializers — pick a base URL or a named environment, and optionally supply a user agent.
init(baseURL: String, appName: String?, userAgent: String?)
init(baseURL: String, appName: String?)
init(baseURL: String, appName: String?, userAgent: String?, chatBaseURL: String?)
init(environment: GeniesEnvironment, appName: String?, userAgent: String?)
init(environment: GeniesEnvironment, appName: String?)
| Property | Type | Notes |
|---|---|---|
baseURL | String | Resolved base URL. |
appName | String | Your app's name. |
userAgent | String | The HTTP User-Agent header sent with SDK network requests — the SDK's own default looks like genies-native-sdk/0.1. Optional; set it to identify your app in request logs. |
environment | GeniesEnvironment | .custom, .development, or .production. |
chatBaseURL | String | The chat service host, separate from the API host. Empty when unset — which leaves chat unconfigured for a custom baseURL. |
A named environment supplies both hosts. With a custom baseURL, chat stays unconfigured unless you also pass chatBaseURL — use the four-argument initializer. Genies supplies both URLs.
Which configure do I call?
There are two entry points, and you call one of them, not both:
| Path | Calls | When |
|---|---|---|
| Core first | GeniesSDK.configure(core:), then auth.configure() | You want the core runtime up before auth — for example to start notifications early. |
| Auth sets up core | auth.configure(environment:appName:appID:) (or any other value-carrying overload) | Simplest path. Auth configures the core runtime for you in one call. |
Calling a value-carrying auth.configure(...) after GeniesSDK.configure(core:) fails with "GeniesSDK core is already configured." Use the no-argument auth.configure() to attach to a core runtime that is already up, and GeniesSDK.shutdown() before reconfiguring.
The no-argument configure() is the attach path — it requires core to be configured already and fails if it isn't. The configure(environment:…) overloads reject .custom; use a baseURL overload for a custom environment.
Credential state
observeCredentialState(_:) delivers a GeniesCredentialEvent with a state and a reason string. Call cancel() on the returned observation to stop.
GeniesCredentialState | Meaning |
|---|---|
.unavailable | No credential. |
.available | A credential is present. |
.refreshed | The credential was renewed. |
.temporarilyUnavailable | Transient failure; may recover. |
.invalidated | The credential is no longer valid — sign in again. |
Auth module
GeniesAuthClient
isConfigured reports whether this client has been configured.
shutdown() is process-wide, not per-instance. Every GeniesAuthClient talks to the same native client, so calling it signs the whole app out. Releasing an instance does not shut down.
Configure
Which overload you call depends on the credentials Genies issued you:
| You have | Sign-in you get | Configure with |
|---|---|---|
| App ID | Magic link | configure(environment:appName:appID:) |
| App ID + client ID | Magic link and federated sign-in | configure(environment:appName:clientID:appID:) |
| Client ID | Federated sign-in | configure(environment:appName:clientID:) |
| Neither | Backend-initiated login (PKCE) | configure(baseURL:appName:) |
Most integrations need only the app ID. The client ID is what federated sign-in authorizes against — without one, signIn fails with "A federated client_id must be configured before signIn". Magic link never uses it.
PKCE is available from any of these rows, including the last. The exchange sends only the code and the verifier, so the app holds no credential of its own — your backend holds the one Genies issued it. All the app needs is a configured base URL.
The full set:
configure(environment:appName:clientID:)
configure(environment:appName:appID:)
configure(environment:appName:clientID:appID:)
configure(baseURL:appName:clientID:)
configure(baseURL:appName:consumerAuthBaseURL:appID:)
configure(baseURL:appName:clientID:consumerAuthBaseURL:appID:)
configure(baseURL:appName:)
configure(core:)
configure(consumerAuthBaseURL:appID:)
configure()
Federated sign-in
Opens the authorize URL in an ASWebAuthenticationSession — never an embedded web view — receives the code on your redirect URL, and exchanges it for a session.
| API | Purpose |
|---|---|
signIn(redirectURL:scope:presentationContextProvider:completion:) | Interactive sign-in. |
signInSilently(redirectURL:scope:presentationContextProvider:completion:) | Same flow with prompt=none. Returns the interactionRequired outcome when the provider has no live session. |
handleCallbackURL(_:) | Feed a Universal Link the system delivered. Returns true when it completed the pending sign-in. |
cancelSignIn() | Cancel an in-flight sign-in. |
redirectURL must be a Universal Link your app has registered — never a custom scheme. On iOS 17.4+ the session delivers the link itself; on earlier versions the system opens your app with it, so forward it from your scene delegate to handleCallbackURL(_:). completion runs on the main queue exactly once per call.
Both take a GeniesFederatedSignInHandler, which receives a GeniesFederatedSignInResult carrying a GeniesFederatedSignInOutcome.
Magic link
| API | Purpose |
|---|---|
startMagicLink(email:) | Start email sign-in. Returns GeniesMagicLinkStartResult. |
startMagicLink(phoneNumber:) | Start SMS sign-in. |
verifyMagicLink(email:code:) | Verify with the emailed code. |
verifyMagicLink(phoneNumber:code:) | Verify with the texted code. |
verifyMagicLink(code:) | Verify when the destination is implied. |
Phone numbers are E.164: 7–15 digits and nothing else, like +12345678901. Spaces, dashes, and parentheses are rejected as invalid_request. The leading + is optional — it's stripped on the way through — but the country code is not: a bare national number passes validation and then texts whichever country those digits happen to name.
Backend-initiated login (PKCE)
Use this when your backend starts the login rather than the app. The app produces a challenge, your backend redeems it with Genies, and the app exchanges the resulting code for a session.
App createCodeVerifier() → codeChallenge
App → your backend codeChallenge
backend → Genies starts the login, gets a one-time code
backend → App code
App exchangeAuthorizationCode(code) → SDK stores the session
| API | Purpose |
|---|---|
createCodeVerifier() | Returns a GeniesAuthPKCEChallenge with codeChallenge and codeChallengeMethod. |
exchangeAuthorizationCode(_:) | Exchange the one-time code your backend returned for a session. |
let challenge = auth.createCodeVerifier()
// Send challenge.codeChallenge to your backend; it returns a one-time code.
let result = try auth.exchangeAuthorizationCode(code)
Things to know:
- Send only
codeChallenge. The method is alwaysS256. The verifier never leaves the device. - The SDK holds the verifier in memory. A later
createCodeVerifier()replaces it, and an app restart between challenge and exchange loses it — the exchange then fails withINVALID_ARGUMENTand you start over. - The code is single-use and expires 60 seconds after your backend receives it.
A backend-initiated login and a magic-link login create different Genies users for the same person, with separate inventories. Pick one flow per user.
Your backend's side of this — machine tokens, granting assets, identifying users — is covered separately in the backend integration guide.
Sessions and tokens
| API | Returns | Purpose |
|---|---|---|
accessToken() | String? | Current access token. |
refreshToken() | String? | Current refresh token. |
refreshConsumerSession() | GeniesAuthResult? | Refresh the consumer session. |
forceRefreshTokens() | GeniesAuthResult? | Force a token refresh. |
tryRestoreSession() | GeniesAuthResult? | Restore a persisted session at launch. |
logout() | GeniesAuthResult? | Log out. |
logoutConsumerSession() | GeniesAuthResult? | Log out the consumer session. |
timeUntilTokensExpire() | Int | Seconds until expiry. |
checkAccessTokenValidity() | Bool | Whether the access token is still valid. |
apisAreReady() | Bool | Whether authenticated calls can be made. |
Inventory module
GeniesInventoryClient
Ownership
| API | Returns | Purpose |
|---|---|---|
owns(assetID:) | GeniesOwnership? | Whether the user owns one asset. |
batchCheckOwns(assetIDs:) | GeniesOwnershipBatchResult? | Split a list into owned and unowned. |
Entitlements
| API | Returns | Purpose |
|---|---|---|
listEntitlements(limit:cursor:) | GeniesEntitlementPage? | Every active entitlement — the only complete enumeration of what the user owns. IDs and grant times only. |
A GeniesEntitlement carries assetID, an optional assetType, and an ISO-8601 grantedAt. Pages carry items and a nextCursor that is nil on the last page.
The user's own items
| API | Returns | Purpose |
|---|---|---|
listOwnedAvatars(kind:) | [GeniesOwnedAvatar]? | The user's avatars, gallery-ready. kind narrows to avatars or smart avatars. |
listOwnedWearables() | [GeniesOwnedWearable]? | The user's wearables. |
Both are unpaginated. listOwnedAvatars costs one inventory scan plus one lookup per 50 avatars; a failed display lookup leaves that row's fields empty and sets its error rather than failing the call.
Catalog
| API | Returns | Purpose |
|---|---|---|
listCatalogAvatars(kind:ownership:free:limit:cursor:) | GeniesCatalogAvatarPage? | Browse published avatars. |
listCatalogWearables(categories:ownership:free:limit:cursor:) | GeniesCatalogWearablePage? | Browse published wearables. categories narrows to any of them. |
Filters are exact-match server-side, so an unrecognized value returns an empty page rather than an error. Pass a previous page's nextCursor as cursor to page forward.
GeniesCatalogOwnership is .all (default), .owned, or .notOwned. Items carry their own owned flag regardless of the filter. GeniesAvatarKind is .all (default), .avatar, or .smartAvatar.
Display data
| API | Returns | Purpose |
|---|---|---|
getAssets(ids:) | [GeniesAsset]? | Display data for IDs you already hold. Results come back in request order; an unresolvable ID sets that asset's error rather than failing the call. |
Avatars
| API | Returns | Purpose |
|---|---|---|
getAvatar(ref:) | GeniesAvatar? | The shared catalog view — what everyone sees. |
getUserAvatar(ref:) | GeniesAvatar? | The signed-in user's view — catalog content merged with their customization layer, via the user resolve. This is what NAF's loadUserAvatar renders. |
saveUserAvatar(ref:wearableIDs:) | GeniesAvatar? | Persist the user's outfit. wearableIDs replaces the saved wearables — an empty array takes everything off. Subspecies and body are kept. |
isWearableID(_:) | Bool | (static) Whether saveUserAvatar accepts an ID as a wearable. |
shutdown() | — | Tear down the client. |
Pass the bm_/vm_ wearable IDs the user is wearing — e.g. avatar.wearables plus their edits. A vm_ ID names a variant and saves as-is. If you're rendering through GeniesPartnerSDKNAF, view.saveOutfit(to:) assembles this list for you.
Avatar types
The types the Inventory module returns when you work with avatars.
GeniesAvatarRef
One way to address an avatar. Wrap whichever identifier you hold — the SDK parses the format and routes internally.
GeniesAvatarRef(id: "bm_smart-avatar_<hex>") // any bm_/vm_ manifest ID
GeniesAvatarRef(avatarID: "...")
GeniesAvatarRef(smartAvatarID: "...")
GeniesAvatarRef(smartAvatarID: "...", avatarID: "...")
| Member | Type | Notes |
|---|---|---|
avatarID | String? | Spawnable avatar identifier, when known. |
smartAvatarID | String? | Full-avatar identifier, when known. |
fetchAvatarID() | String? | The plain avatar ID for NAF's spawn API. Hits the network only when the ref doesn't already carry it; cached for the process. |
There is no readable id property, because a ref can hold both identifiers at once. Malformed, unsupported, and um_ IDs fail at call time with INVALID_ARGUMENT.
GeniesAvatar
Everything you need to show an avatar in your UI and hand it to NAF: its name, what it's wearing, whether it can chat, and the identifiers NAF needs to render it.
It deliberately contains no meshes or textures — those are NAF's job. Pass the ref (or fetchAvatarID()) to NAF to actually draw the avatar.
| Property | Type | Notes |
|---|---|---|
ref | GeniesAvatarRef | Identifiers, merged from your input and the response. |
canChat | Bool | True only for a smart avatar. |
name | String | Empty when unnamed. |
brainID / behaviorID / voiceID | String? | What a smart avatar is made of; nil for a plain avatar. |
wearables | [GeniesAsset] | What the avatar is wearing. Each assetID is ready for NAF's equip API. |
json | String | The full resolve payload, for anything not surfaced above. |
Rows in a list
GeniesOwnedAvatar (ref, canChat, name, error, json) and GeniesCatalogAvatar (ref, canChat, name, owned, free, json) are the list forms. GeniesOwnedWearable and GeniesCatalogWearable are the wearable equivalents, keyed by assetID with an optional category and icon.
GeniesAssetCategory is extensible — the backend doesn't constrain wearable categories, so a new value arrives as .init(rawValue: "gloves"). Known constants include hair, hat, glasses, mask, earrings, bracelet, shirt, hoodie, jacket, dress, pants, shorts, skirt, shoes, plus avatar and smartAvatar.
Notifications module
GeniesNotificationsClient
A live stream over the SDK's WebSocket gateway. Reconnect, acking, and duplicate suppression are handled for you.
Requires GeniesSDK to be configured first — the endpoint and bearer token both come from the shared runtime, and the token is re-read on every reconnect.
| Member | Purpose |
|---|---|
shared | The shared client. |
delegate | Your GeniesNotificationsDelegate. |
callbackQueue | Where delegate callbacks are delivered. Defaults to the main queue; set before start(). |
start() | Connect, or return true if already connected. |
start(url:) | Connect against an overridden gateway URL. |
stop() | Disconnect and cancel any pending reconnect. The client stays usable. |
shutdown() | Release the native client and delegate. Use when tearing the SDK down, not between connections. |
connectionState / connected | Current state. |
resolvedGatewayURL | The URL resolved on the last start(). nil before the first one — check this first when a connection is refused. |
hadAuthorizationAtStart | Whether a bearer token was present at the last start(). false means no session reached the client. |
Subscribe the delegate before calling start(). Notifications that arrive before there is a delegate are acked and dropped, not queued.
GeniesNotificationsDelegate
All methods are optional.
| Callback | Fires when |
|---|---|
notificationsDidChangeInventory(_:) | An entitlement was granted or revoked. |
notificationsDidChangeConnectionState(_:) | The connection state changed. |
notificationsDidFail(_:) | A frame could not be decoded, or a protocol fault occurred. Reported and skipped — it never tears the connection down. |
GeniesInventoryChange carries change (a GeniesInventoryChangeKind — gained or lost), ownedList (a GeniesOwnedListKind, naming which list to refresh), assetID, an ISO-8601 occurredAt, and the full payload. The backend commits the entitlement before emitting, so a list call made from this callback already reflects it — refresh the list named by ownedList.
GeniesNotificationsConnectionState | Meaning |
|---|---|
.reconnecting | Retrying. |
.disconnected | Gave up — the gateway rejected the identity, or retries were exhausted. |
Errors
Every error from this SDK is an NSError in the GeniesSDKErrorDomain. A category on NSError gives typed access, so you never type string keys:
| Property | Type | Notes |
|---|---|---|
errorCode | GeniesErrorCode | The backend's code when there was one, else the SDK's own. Never nil. |
httpStatus | Int | Upstream HTTP status, or 0 when the request never got a response. |
downstreamCode | String? | The nested service's code — what tells a bare FORBIDDEN apart from a NOT_ENTITLED behind the same 403. |
responseBody | String? | The raw body, always kept so an unmapped failure is diagnosable. |
It's errorCode, not code. NSError already owns an NSInteger code, and shadowing it silently breaks error.code.
GeniesErrorCode is an extensible string enum — backend codes are passed through rather than translated, so a code we've never seen still reaches you as its raw string. Switch on the cases you handle and keep a default.
Backend codes include unauthenticated, forbiddenScope, forbiddenOrg, notEntitled, fieldLocked, notFound, invalidReference, conflict, rateLimited, and upstreamUnavailable. Auth uses the RFC 6749 OAuth envelope: invalidGrant, invalidRequest, invalidClient, unauthorizedClient.
Raised by the SDK itself: invalidArgument, clientNotInitialized, transportError (never reached a response — offline, DNS, timeout), deserializeError (a response arrived but didn't match the contract), and httpError (a failure the backend didn't label — read httpStatus and responseBody).
Numeric GeniesSDKErrorCode values are grouped per service, so the number alone says which raised it: core 1, auth 10, avatar 20, inventory 30, notifications 40, and native bridge faults 90–93.
Per-row errors
Several list calls succeed even when individual rows fail. GeniesAsset, GeniesOwnedAvatar, and GeniesOwnedWearable each carry an optional GeniesAssetError (code, message) — check it per row, since the call itself won't throw.