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.
| Module | Entry point | Package |
|---|---|---|
| (shared runtime) | GeniesSDK (object) | com.genies.auth |
| Auth | GeniesAuth | com.genies.auth |
| Inventory | GeniesInventory | com.genies.inventory |
| Notifications | GeniesNotifications (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.
| API | Purpose |
|---|---|
configure(configuration: GeniesCoreConfiguration) | Configure the shared runtime. |
configure(...) | Overload taking the configuration fields directly. |
isConfigured: Boolean | Whether 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
| API | Returns |
|---|---|
owns(assetId: String) | GeniesOwnership |
batchCheckOwns(assetIds: List<String>) | GeniesOwnershipBatchResult — splits into owned and unowned |
Entitlements
| API | Returns |
|---|---|
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
| API | Returns |
|---|---|
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
| API | Returns |
|---|---|
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
| API | Returns |
|---|---|
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() | — |
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.
| API | Purpose |
|---|---|
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. |
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.
| Callback | Fires 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.