---
title: "Unreal SDK reference"
description: "Blueprint nodes, C++ completion delegates, mobile lifecycle, and feature receipts."
sidebar:
  label: "Unreal"
search:
  tags: ["sdk", "reference", "unreal"]
  keywords: ["Blueprint", "C++", "Unreal", "configure", "identify", "consumeFeature", "App Action"]
---

`UNuxieSubsystem` provides Nuxie's Blueprint and C++ interfaces. It belongs to your GameInstance and survives map travel. [Install and configure the plugin](/docs/sdks/unreal) before calling it.

<span id="interfaces-and-contracts" />

## Configuration

Call **Configure (Nuxie)** or `Configure(Options, Completion)` with `FNuxieOptions`:

| Field | Default | Description |
| --- | --- | --- |
| `IOSPublicKey`, `AndroidPublicKey` | Running platform's key required | Publishable app keys. |
| `Environment` | `Production` | `Production` or `Development`. |
| `LogLevel` | `Warning` | `Warning`, `Debug`, `Info`, `Error`, `None`, or `Verbose`. |
| `Locale` | Empty | Empty uses the device locale. |
| `BillingMode` | `Native` | `Native` or `External`. |
| `ExternalController` | Unset | UObject implementing the purchase controller interface for external billing. |

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.

Wait for successful configuration before making requests. `GetStatus()` reads lifecycle state without a request; `OnStatusChanged` reports changes. Await a successful `Shutdown` completion before configuring a different session.

## Identify a player

Use **Identify (Nuxie)** with your player ID. In C++, call `Identify(CustomerId, Options, Completion)` with an `FNuxieIdentityOptions` value and an `FNuxieCompletion` delegate.

`GetIdentity` returns the customer ID, anonymous ID, and identified flag. **Reset (Nuxie)** clears the identified player and creates a new anonymous ID.

`FNuxieIdentityOptions` provides `Properties` and `PropertiesSetOnce`. Use the latter for attributes that should be written only when absent. Await the identity completion before sending requests for that player.

Call **SetLocale (Nuxie)** or `SetLocale(Locale, Completion)` to change the app's locale. An empty string restores the device locale.

## Trigger an Experience

In Blueprint, connect the relevant game event to **Trigger (Nuxie)**. In C++:

```cpp
#include "NuxieSubsystem.h"

UNuxieSubsystem* Nuxie =
    GetGameInstance()->GetSubsystem<UNuxieSubsystem>();

Nuxie->Trigger(TEXT("shop_requested"), FNuxieProperties{},
    FNuxieCompletion::CreateLambda([](const FNuxieResult& Result)
    {
        if (!Result.IsSuccess())
        {
            // Handle Result.GetError().
        }
    }));
```

A successful completion means the event was accepted. Presentation depends on the published trigger and audience. **Dismiss (Nuxie)** closes the current presentation.

### Properties

`Trigger` and identity options accept `FNuxieProperties`. Use `WithString`, `WithBool`, `WithInteger`, `WithNumber`, `WithNull`, `WithObject`, or `WithArray` to add values. Each builder returns a Boolean and writes an error string; the value changes only on success.

In Blueprint, use **Make Properties**, the typed value constructors, and **With Property**. JSON numbers must be finite. Integer inputs must be within `±9,007,199,254,740,991`. `FNuxieProperties::TryParse` accepts a JSON object; `FNuxieJsonValue::TryParse` also accepts arrays and scalar values.

## Observe feature access

In Blueprint, use **Observe Nuxie Feature** with the Feature key. Its `StateChanged` event includes readiness and `bHasAccess`. Show a loading state while readiness is `Unknown`. When `bHasAccess` is true, read `Access.bAllowed` to decide whether the player can use the feature. Cancel the observer when the widget is destroyed.

In C++, `GetFeatureState()` reads local state. `CheckFeature()` queries access with an `FNuxieFeatureQuery`, including `RequiredBalance`, `EntityId`, and the cache policy.

### Access values

`FNuxieFeatureQuery.RequiredBalance` defaults to `1`; `EntityId` is optional. `Policy` is `CacheFirst` by default or `Remote` for a server request. Queries do not consume an allowance.

`FNuxieFeatureAccess` contains `bAllowed`, `bUnlimited`, `bHasBalance`, `Balance`, and `Type` (`Boolean`, `Metered`, or `CreditSystem`). Read `Balance` only when `bHasBalance` is true.

`GetFeatureSnapshot()` returns readiness, `CustomerId`, `IdentityGeneration`, `Revision`, and the `All` feature map. The counters are decimal strings. Observe `OnFeaturesChanged` for updates; use snapshots for UI and consumption receipts to authorize spending.

## Consume usage

Call **ConsumeFeature (Nuxie)** with an `FNuxieFeatureCommand` containing:

| Field | Value |
| --- | --- |
| `OperationId` | A saved ID for this action; reuse it for retries. |
| `Quantity` | The positive whole number of units to deduct. |
| `EntityId` | Optional entity assigned the allowance. |

The Success output provides a receipt. Check `bAccepted` before applying the game action. Success can return a denied receipt; an accepted final use can leave a zero balance. Apply each accepted operation only once in your game.

The receipt includes `CustomerId`, `FeatureId`, `OperationId`, `Quantity`, `bAccepted`, `Code`, `Balance`, `bUnlimited`, `bActive`, and `bIdempotentReplay`. Check `bHasBalance` before reading `Balance`, and `bHasOccurredAt` before reading `OccurredAtMs`. A replay returns a previous operation's result without another charge.

`Quantity` and query `RequiredBalance` must be positive integers up to `9,007,199,254,740,991`. For shared credits, submit the credit feature's key with the action's cost. An error or timeout does not undo a charge; keep the operation ID for a retry.

## Checkout integration

For your existing billing provider, select `External` billing and supply a UObject implementing `INuxiePurchaseController`. Implement the Blueprint native events:

| Event | Request |
| --- | --- |
| `BeginPurchase` | `UNuxiePurchaseRequest`, including the selected `Product` |
| `BeginRestore` | `UNuxieRestoreRequest` |

Retain the request while your provider works. Finish purchases with `TryComplete(Outcome, Message)` using `ENuxiePurchaseOutcome::Purchased`, `Cancelled`, `Pending`, or `Failed`. Restores use `ENuxieRestoreOutcome::Restored`, `NoPurchases`, or `Failed`.

`IsPending()` reports whether a request still accepts a result. `TryComplete()` returns false after a request has already completed or expired. Return the actual provider result; opening checkout is not a purchase.

The request's `FNuxieStoreProduct` contains `Platform`, `ProductId`, `StoreProductId`, and `PlacementId`, plus optional product and offer fields:

| Fields | Presence flag |
| --- | --- |
| `DisplayName`, `Description`, `DisplayPrice`, `ProductType` | `bHasDisplayName`, `bHasDescription`, `bHasDisplayPrice`, `bHasProductType` |
| `Period`, `PeriodCount`, `BillingPlan` | `bHasPeriod`, `bHasPeriodCount`, `bHasBillingPlan` |
| `EligibilityJws`, `IntroductoryTerms` | `bHasEligibilityJws`, `bHasIntroductoryTerms` |
| `BasePlanId`, `PurchaseOptionId`, `OfferId` | `bHasBasePlanId`, `bHasPurchaseOptionId`, `bHasOfferId` |
| `PricingPhases` | `bHasPricingPhases` |

Check each presence flag before reading its value. `FNuxieIntroductoryTerms` includes `DisplayPrice`, `Period`, `PeriodCount`, `Cycles`, `PaymentMode`, and `DisplayDuration`. Each `FNuxiePricingPhase` includes `DisplayPrice`, `BillingPeriod`, `BillingCycleCount`, and `RecurrenceMode`.

Preserve these terms when launching checkout. Your provider owns transaction finishing and acknowledgement in external mode. Restores requested by an Experience reach `BeginRestore`.

## App Actions and callbacks

`OnAppAction` connects an Experience to your game, such as opening the shop after onboarding. Match the action's `Name` to a handler and read its `Payload` for supplied values. `OnActivity` receives runtime activity. All callbacks run on the game thread. C++ completions support `CreateWeakLambda` for callbacks owned by a UObject.

Your game controls pause, input, and audio while an Experience is visible.

| Event | Purpose |
| --- | --- |
| `OnStatusChanged` | Configuration and shutdown state. |
| `OnIdentityChanged` | Current customer identity. |
| `OnFeaturesChanged` | Full access snapshot. |
| `OnActivity` | Experience activity with name, timestamps, and properties. |
| `OnAppAction` | An authored action's name, payload, and Experience context. |
| `OnError` | Errors delivered outside a request completion. |

## Results, errors, and cleanup

Blueprint async nodes provide typed Success and Failure outputs. In C++, check `FNuxieResult::IsSuccess()` before reading a typed result's `GetValue()`. Use `GetError()` on failure.

`FNuxieError` contains `Code`, `Message`, `NativeCode`, and `Details`. Codes include `InvalidArgument`, `NotConfigured`, `AlreadyConfigured`, `LifecycleBusy`, `IdentityChanged`, `SessionInUse`, `SDKShutdown`, `OperationTimeout`, `InvalidResponse`, `IncompatibleBridge`, `NativeError`, `UnsupportedPlatform`, and `Overloaded`. Branch on the code rather than message text.

If a request returns `Overloaded`, retry after outstanding requests finish. Register and remove delegates with their owning object, cancel feature observers when widgets are destroyed, and use `Shutdown` when ending the SDK session. Map travel does not require shutdown.

<span id="shared-platform-behavior" />

See [Features and entitlements](/docs/monetization/features-and-entitlements) for access configuration. The [API reference](https://github.com/nuxieai/nuxie-ue/blob/main/docs/api-reference.md) and [public types](https://github.com/nuxieai/nuxie-ue/blob/main/Source/Nuxie/Public/NuxieTypes.h) list all fields and Blueprint nodes.