Skip to main content

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.

ModuleEntry pointCovers
(shared runtime)GeniesSDKConfiguration and lifecycle
AuthGeniesAuthClientSign-in, sessions, tokens
InventoryGeniesInventoryClientOwnership, entitlements, avatars, catalog
NotificationsGeniesNotificationsClientLive 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​

APIPurpose
configure(core:)Configure the shared runtime from a GeniesCoreConfiguration. Throws on failure.
isConfiguredWhether 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?)
PropertyTypeNotes
baseURLStringResolved base URL.
appNameStringYour app's name.
userAgentStringThe 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.
environmentGeniesEnvironment.custom, .development, or .production.
chatBaseURLStringThe chat service host, separate from the API host. Empty when unset — which leaves chat unconfigured for a custom baseURL.
note

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:

PathCallsWhen
Core firstGeniesSDK.configure(core:), then auth.configure()You want the core runtime up before auth — for example to start notifications early.
Auth sets up coreauth.configure(environment:appName:appID:) (or any other value-carrying overload)Simplest path. Auth configures the core runtime for you in one call.
caution

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.

GeniesCredentialStateMeaning
.unavailableNo credential.
.availableA credential is present.
.refreshedThe credential was renewed.
.temporarilyUnavailableTransient failure; may recover.
.invalidatedThe credential is no longer valid — sign in again.

Auth module​

GeniesAuthClient​

isConfigured reports whether this client has been configured.

caution

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 haveSign-in you getConfigure with
App IDMagic linkconfigure(environment:appName:appID:)
App ID + client IDMagic link and federated sign-inconfigure(environment:appName:clientID:appID:)
Client IDFederated sign-inconfigure(environment:appName:clientID:)
NeitherBackend-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.

APIPurpose
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.

APIPurpose
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
APIPurpose
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 always S256. 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 with INVALID_ARGUMENT and you start over.
  • The code is single-use and expires 60 seconds after your backend receives it.
caution

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​

APIReturnsPurpose
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()IntSeconds until expiry.
checkAccessTokenValidity()BoolWhether the access token is still valid.
apisAreReady()BoolWhether authenticated calls can be made.

Inventory module​

GeniesInventoryClient​

Ownership​

APIReturnsPurpose
owns(assetID:)GeniesOwnership?Whether the user owns one asset.
batchCheckOwns(assetIDs:)GeniesOwnershipBatchResult?Split a list into owned and unowned.

Entitlements​

APIReturnsPurpose
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​

APIReturnsPurpose
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​

APIReturnsPurpose
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​

APIReturnsPurpose
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​

APIReturnsPurpose
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.
tip

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: "...")
MemberTypeNotes
avatarIDString?Spawnable avatar identifier, when known.
smartAvatarIDString?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.

PropertyTypeNotes
refGeniesAvatarRefIdentifiers, merged from your input and the response.
canChatBoolTrue only for a smart avatar.
nameStringEmpty when unnamed.
brainID / behaviorID / voiceIDString?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.
jsonStringThe 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.

MemberPurpose
sharedThe shared client.
delegateYour GeniesNotificationsDelegate.
callbackQueueWhere 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 / connectedCurrent state.
resolvedGatewayURLThe URL resolved on the last start(). nil before the first one — check this first when a connection is refused.
hadAuthorizationAtStartWhether a bearer token was present at the last start(). false means no session reached the client.
caution

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.

CallbackFires 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.

GeniesNotificationsConnectionStateMeaning
.reconnectingRetrying.
.disconnectedGave 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:

PropertyTypeNotes
errorCodeGeniesErrorCodeThe backend's code when there was one, else the SDK's own. Never nil.
httpStatusIntUpstream HTTP status, or 0 when the request never got a response.
downstreamCodeString?The nested service's code — what tells a bare FORBIDDEN apart from a NOT_ENTITLED behind the same 403.
responseBodyString?The raw body, always kept so an unmapped failure is diagnosable.
note

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.