Android SDK reference

Kotlin setup, identity, event capture, feature access, and native purchase interfaces.

The Android SDK provides Kotlin methods for customer identity, Experiences, purchases, and feature access. Install and configure the SDK before calling these methods.

Configuration

Create a NuxieConfiguration and pass it to Nuxie.setup(context, configuration) once at app launch. The SDK uses the application context.

Use the public pk_test_ key for preview content and the pk_live_ key for live content. Keep the default service environment for both. The development environment selects a separate Nuxie service; it does not select test mode for your app.

Nuxie.isSetup reports whether local setup has completed.

Identify a customer

Use your application’s customer ID to associate events and access with an account:

import ai.nuxie.sdk.Nuxie

Nuxie.identify(
    "customer_123",
    userProperties = mapOf("plan" to "pro")
)

Nuxie.distinctId returns the current ID. On sign-out, call Nuxie.reset() to clear the identified customer and generate a new anonymous ID.

Customer properties

identify() accepts userProperties for values to update and userPropertiesSetOnce for values to set only when absent. Both are optional maps of JSON values.

Nuxie.anonymousId returns the anonymous ID, and Nuxie.isIdentified tells you whether the current customer has been identified. reset(keepAnonymousId = true) retains the anonymous ID; the default rotates it for sign-out.

Locale

Call the suspending setLocaleIdentifier(localeIdentifier) to change the app’s locale. Pass null to follow the device again. The change takes effect when the SDK next synchronizes the profile.

Trigger an Experience

Nuxie.trigger("upgrade_requested", mapOf("source" to "settings"))

The event name must match a published trigger. The call returns immediately; Nuxie checks the audience and re-entry rules before presenting. Use Nuxie.dismiss() from a coroutine to close a presented Experience.

Check access

Call hasFeature() from a coroutine:

val access = Nuxie.hasFeature("premium-export")
if (access.allowed) {
    // Enable premium export.
}

The default CACHE_FIRST policy uses fresh cached access. Pass policy = FeatureCheckPolicy.REMOTE to query the server. requiredBalance and entityId select the amount and entity to check. A check does not consume usage.

Access values and local state

FeatureAccess contains allowed, unlimited, an optional balance, and a feature type. A Boolean feature expresses access; metered and credit features can also have balances.

Nuxie.features exposes StateFlow values for snapshot, state, and all. Collect the snapshot to receive access and readiness from the same update. It includes identityGeneration and revision alongside the feature map.

State is FeatureInfo.State.Unknown, Reconciling, or Ready. Show a loading state while access is Unknown; Reconciling means purchase access is being synchronized. Call awaitReady() to suspend until access is ready. isAllowed(featureId) and balance(featureId) read cached global access without a request. Use this state to render UI and a consumption result to authorize spending.

Record usage

useFeature(featureId, amount = 1.0, entityId = null, metadata = null) records usage without returning a result. Use it when the app does not need to wait for acceptance.

useFeatureAndWait(featureId, amount = 1.0, entityId = null, setUsage = false, metadata = null) is suspending and returns FeatureUsageResult: success, featureId, amountUsed, optional message, optional usage, and optional authoritativeAccess. usage contains current, optional limit, and optional remaining.

With setUsage = true, amount is a cumulative total for that customer, feature, and entity. Sending 20 and then 25 consumes 20 units and then five more. Sending a lower total does not refund usage.

Use consumeFeature() when your app needs a saved operation ID for retries.

Consume usage

val receipt = Nuxie.consumeFeature(
    "credits",
    quantity = 5.0,
    operationId = "generation_123"
)
if (receipt.accepted) {
    // Start the generation once.
}

Save one operation ID for each action and reuse it when retrying. accepted determines whether the action was charged; a successful final-unit consumption can leave a zero balance. Handle request errors without starting the work.

Consumption result

FeatureConsumptionResult includes the following fields:

quantity must be a positive whole number no greater than 9,007,199,254,740,991. Supply entityId when spending an entity-specific allowance. For shared credits, use the credit feature’s key and the number of credits the action costs.

Purchases

Published purchase buttons use the configured checkout integration. For an app-owned checkout entry point, purchase(activity, product, replacement = null) is suspending and returns PurchaseResult.Purchased, Cancelled, Pending, or Failed(cause).

A StoreProduct identifies the selection shown to the customer: productId, storeProductId, optional basePlanId, purchaseOptionId, offerId, and placementId. rawProduct holds the corresponding Google Play ProductDetails when available. Forward isOfferPersonalized to your purchase provider.

When replacing an active subscription, provide SubscriptionReplacement(oldPurchaseToken, replacementMode). The supported modes are WITH_TIME_PRORATION, CHARGE_PRORATED_PRICE, WITHOUT_PRORATION, CHARGE_FULL_PRICE, and DEFERRED. A checkout requiring replacement fails with SubscriptionReplacementRequiredException when that choice is missing.

External checkout

Implement NuxiePurchaseDelegate with two suspending methods:

• purchase(product: StoreProduct): PurchaseResult
• restorePurchases(): RestoreResult

Set the delegate on the configuration before setup. Use PurchaseHandlingMode.APP_MANAGED when your app or provider owns Google Play acknowledgement and consumption. The default NUXIE_MANAGED mode lets Nuxie complete native purchases. After setup, setPurchaseDelegate() and setPurchaseHandlingMode() change these choices; passing a null delegate returns to native checkout.

Return the actual checkout outcome. Opening a purchase dialog does not mean a purchase succeeded. Observe feature access for the resulting entitlement.

Restore purchases

Nuxie.restorePurchases() is a suspending method. It returns RestoreResult.Restored, NoPurchases, or Failed(cause) through the configured native or external purchase integration.

For existing provider checkout, see the RevenueCat and Superwall adapters.

App Actions

Set Nuxie.listener to a NuxieListener when an Experience needs to call your app, such as opening the export screen after onboarding. Its onAppActionRequested callback receives the action name and payload. The listener also supports activity and feature-access callbacks.

Keep the listener in an app-owned property: the SDK holds it weakly. Callbacks run on Android’s main thread.

Listener callbacks

An App Action includes its name, payload, and Experience context. Route only action names your app recognizes. Clear or replace listeners when their owner no longer needs callbacks.

NuxieActivityInfo exposes id, customerId, timestampMillis, receivedAtMillis, typed activity, and an analytics-ready name and properties. Check isCurrentIdentity before applying an activity to customer-specific UI. Forward analytics with the activity’s original customer ID.

Errors and shutdown

Catch failures from suspending feature and lifecycle methods. A request failure does not establish that a customer lacks access. For a consumption retry, reuse the same operation ID so a delayed response cannot cause a second charge.

Use shutdownAndAwait() from a coroutine when you need to wait for cleanup before configuring another session. shutdown() starts cleanup without waiting. Call purchase-owner setters only after setup and before shutdown; an inactive SDK rejects those changes.

See Delivery for trigger rules and Features and entitlements for access configuration. The public API declaration lists all signatures.