Skip to main content

Partner SDK API

The Genies Partner SDK gives you three modules, each in its own package. Rendering is NAF's job — see the NAF API.

ModuleEntry pointPackage
(shared runtime)GeniesSDK (object)com.genies.auth
AuthGeniesAuthcom.genies.auth
InventoryGeniesInventorycom.genies.inventory
NotificationsGeniesNotifications (object)com.genies.notifications

Calls that can fail throw — GeniesInventoryException and GeniesNotificationsException both carry a GeniesErrorCode.


Configuration and lifecycle​

GeniesSDK​

A singleton. Configure once at launch, before any other call.

APIPurpose
configure(configuration: GeniesCoreConfiguration)Configure the shared runtime.
configure(...)Overload taking the configuration fields directly.
isConfigured: BooleanWhether configuration has completed.
credentialState: StateFlow<GeniesCredentialEvent>Observe session credential changes.
shutdown()Tear down the shared runtime.

GeniesCoreConfiguration carries baseUrl, appName, and userAgent — the last being the HTTP User-Agent header sent with SDK network requests (the SDK's own default looks like genies-native-sdk/0.1). Genies supplies the base URL for your environment.

A GeniesCredentialEvent carries a state and a reason. Because credentialState is a StateFlow, collect it to react to sign-in and expiry:

lifecycleScope.launch {
GeniesSDK.credentialState.collect { event ->
// event.state, event.reason
}
}

Auth module​

GeniesAuth​

Configured with either GeniesAuthConfiguration (baseUrl, appName, clientId, consumerAuthBaseUrl, consumerAppId) or the environment-based form (environment, appName, clientId, appId). initializeWithAppId(context:environment:appName:appId:) is the shorthand for the common case.

Most integrations need only the app ID, which is all magic-link sign-in uses. The client ID is what federated sign-in authorizes against; environment configuration requires one or the other. Backend-initiated login (PKCE) needs neither — the exchange sends only the code and the verifier, so a baseUrl-only configuration is enough and your backend holds the credential.

Sign-in covers federated and magic-link flows. A GeniesFederatedSignInResult carries an outcome, the result, and an optional identityProviderError; implement onResult(result:) to receive it. PKCE is available through a challenge carrying codeChallenge and codeChallengeMethod.

A GeniesAuthResult carries succeeded and message. Failures carry a GeniesErrorCode, httpStatus, requestId, and body.


Inventory module​

GeniesInventory​

Ownership​

APIReturns
owns(assetId: String)GeniesOwnership
batchCheckOwns(assetIds: List<String>)GeniesOwnershipBatchResult — splits into owned and unowned

Entitlements​

APIReturns
listEntitlements(...)A page of GeniesEntitlement, each with assetId, optional assetType, and an ISO-8601 grantedAt

Every active entitlement — the only complete enumeration of what the user owns. IDs and grant times only; use the owned lists for display data. nextCursor is null on the last page.

The user's own items​

APIReturns
listOwnedAvatars(kind: GeniesAvatarKind = GeniesAvatarKind.All)List<GeniesOwnedAvatar>
listOwnedWearables()List<GeniesOwnedWearable>

Both are unpaginated and gallery-ready. A failed display lookup leaves that row's fields empty and sets its error rather than failing the call.

Catalog​

APIReturns
listCatalogAvatars(...)A page of GeniesCatalogAvatar
listCatalogWearables(...)A page of GeniesCatalogWearable

Filters are exact-match server-side, so an unrecognized value returns an empty page rather than an error. Pass a previous page's nextCursor to page forward. Ownership filtering uses GeniesCatalogOwnership; items carry their own owned flag regardless.

Display data and avatars​

APIReturns
getAssets(ids: List<String>)List<GeniesAsset> — results in request order; an unresolvable ID sets that asset's error
getAvatar(ref: GeniesAvatarRef)GeniesAvatar — the shared catalog view
getUserAvatar(ref: GeniesAvatarRef)GeniesAvatar — the user's view, with their customization layer
saveUserAvatar(ref: GeniesAvatarRef, wearableIds: List<String>)GeniesAvatar — wearableIds replaces the saved wearables (empty takes everything off); subspecies and body are kept
shutdown()—
tip

Pass the bm_/vm_ wearable IDs the user is wearing — e.g. the avatar's wearables plus their edits. A vm_ ID names a variant and saves as-is.


Avatar types​

The types the Inventory module returns when you work with avatars.

GeniesAvatarRef​

Wrap whichever identifier you hold — the SDK parses the format and routes internally.

GeniesAvatarRef.avatar(avatarId)
GeniesAvatarRef.smartAvatar(smartAvatarId)
GeniesAvatarRef.of(smartAvatarId, avatarId)

val avatarId = ref.fetchAvatarId() // the plain ID for NAF's spawn API

fetchAvatarId() hits the network only when the ref doesn't already carry the ID, and the result is cached for the process.

GeniesAvatar​

Everything you need to show an avatar in your UI and hand it to NAF. It deliberately contains no meshes or textures — those are NAF's job; pass the ref (or fetchAvatarId()) to NAF to actually draw it. It exposes ref, canChat, name, the smart-avatar brainId / behaviorId / voiceId, the wearables the avatar is wearing, and the full json payload.

canChat is true only for a smart avatar. GeniesAvatarKind is All, Avatar, or SmartAvatar.


Notifications module​

GeniesNotifications​

A singleton streaming live inventory changes. Requires GeniesSDK to be configured first — the endpoint and bearer token both come from the shared runtime.

APIPurpose
setListener(...)Register a GeniesNotificationsListener.
start(url: String? = null)Connect, optionally against an overridden gateway URL.
stop()Disconnect and cancel any pending reconnect.
shutdown()Release the native client and listener.
caution

Register the listener before calling start(). Notifications that arrive before there is a listener are acked and dropped, not queued.

GeniesNotificationsListener​

All callbacks have default no-op implementations.

CallbackFires when
onInventoryChanged(change)An entitlement was granted or revoked.
onConnectionStateChanged(state)The connection state changed.
onError(error)A frame could not be decoded, or a protocol fault occurred.

GeniesInventoryChange carries change, ownedList, assetId, an ISO-8601 occurredAt, and the full payload as a JSONObject. The backend commits the entitlement before emitting, so a list call made from this callback already reflects it.


Errors​

GeniesErrorCode is shared across the SDK. Backend codes are passed through rather than translated, so a code we've never seen still reaches you — handle the cases you care about and keep an else branch.

GeniesInventoryException and GeniesNotificationsException carry an errorCode plus the raw response body, kept so an unmapped failure stays diagnosable.

Per-row errors​

Several list calls succeed even when individual rows fail. GeniesAsset, GeniesOwnedAvatar, and GeniesOwnedWearable each carry an optional error — check it per row, since the call itself won't throw.