Getting started

Welcome to the Noctua SDK for Unity! This guide will walk you through integrating our SDK into your Unity project. Follow these steps to set up the SDK, configure platform-specific settings, and initialize Noctua features in your game.

Preparation

Before diving into the integration process, let's ensure you have everything you need to successfully integrate the Noctua SDK into your Unity project.

Get SDK Configuration Files

To use the Noctua SDK, you must have at least the main configuration file named noctuagg.json. Depending on your publishing arrangements, additional files, such as google-services.json or GoogleService-Info.plist from Firebase, may also be required.

Configuration Parameters

• isOfflineFirst (boolean) - Set to true if the game supports offline-first functionality.
• welcomeToastDisabled (boolean) - Set to true to disable the welcome toast notification.

Please put your configuration files under the Assets/StreamingAssets/ directory.

Offline-First Guide and Behaviours

When offline-first feature is active and the user's device is offline, InitAsync will keep preparing the SDK, mark the session as offline and return success without exception. If it returns an exception, it will be because of other reasons and you need to handle it.

However, AuthenticateAsync will throw an exception if the user's device is offline and you need to handle it on your own depending on your game's logic, like whether you really need to retrieve SDK's user bundle object.

If the AuthenticateAsync exception is caused by "Networking" issue, you can keep track "login" event and allow the user to continue to run as normal.

try {
    var userBundle = await Noctua.Auth.AuthenticateAsync();
    // Use the userBundle for pairing player ID

    // If the player ID in the user bundle is null or 0, there's no need to sync with the game side.
    // This is an intentional trade-off to support the offline-first feature.
    // var playerID = userBundle?.Player?.Id ?? 0;
    // Debug.Log("User is authenticated with Player ID: " + playerID);

}
catch (Exception e)
{
    if (e.Message.Contains("Networking")) // Offline
    {
        // Track login event
        Noctua.Event.TrackCustomEvent("login");

        // Then continue to gameplay
    } else {
        // Throw or handle the error
        throw e;
    }
}

In offline mode, the game will not be able to access few features of the Noctua SDK, which are:

1. In-App Purchase
2. Platform Content Webview, like customer support, reward, announcement, and more

Any attempt to access these features will trigger UI dialog to remind user to connect to the internet before continue/retry.

Migration Guide

If you are migrating from the Quick SDK to Noctua SDK (UPM), here are the key changes:

Key Optimizations

• No more bridging with iOS & Android native.
• Product code replaced with bundleId and platform for game identification.
• Centralized SDK configuration via noctuagg.json, which includes event tracking settings (Adjust, Facebook, Firebase, etc.).
• Optimized event tracking with a single method supporting multiple services.

SDK Initialization

Old SDK

public void init(Activity activity, String productCode, QuickGameManager.SDKCallback sdkCallback)

New SDK

try
{
    await Noctua.InitAsync();
}
catch (NoctuaException e)
{
    // Handle the exception
}

SDK Authentication

Old SDK

public void freeLogin(Activity activity)

New SDK

private async UniTask Authenticate()
{
    try {
        var user = await Noctua.Auth.AuthenticateAsync();
        Debug.Log("PlayerId: " + user.Player.Id);
    } catch (Exception e) {
        Debug.Log("Exception: " + e);
    }
}

SDK Purchase Flow

Old SDK

QGOrderInfo orderInfo = new QGOrderInfo();
orderInfo.setOrderSubject("Goods Name");
orderInfo.setProductOrderId("Game Unique Order No.");
sdkInstance.pay(this, orderInfo, roleInfo, new QuickGameManager.QGPaymentCallback() { ... });

New SDK

try {
    var purchaseResponse = await Noctua.IAP.PurchaseItemAsync(new PurchaseRequest
    {
        ProductId = productId,
        Price = 0.1m,
        Currency = "USD",
        IngameItemId = "789",
        IngameItemName = "Skin X"
    });

    if (purchaseResponse.Status == OrderStatus.Completed)
    {
        Debug.Log("Purchase was successful!");
    }
} catch (Exception e) {
    Debug.Log("Exception: " + e);
}

Callback OnPurchaseDone

Noctua.IAP.OnPurchaseDone += order =>
{
    Debug.Log("Event arrived on game side -> OnPurchaseDone, orderID: " + order.Id);
    outputConsole.text = "Event arrived on game side -> OnPurchaseDone, orderID: " + order.Id;
};

Event Tracking

Old SDK

public void trackAdjustEvent(String eventToken);
public void logCustomEvent(String eventName, Bundle bundle);
public void logEvent(String eventName, Bundle parameters);

New SDK

Noctua.Event.TrackCustomEvent("my_event", new Dictionary<string, object>() {
    { "key", "value" }
});

Getting help

We're here to support you throughout your integration process. If you encounter any issues or have questions, here are two ways to get assistance:

Submit an issue

For technical issues, bug reports, or feature requests:

• Visit our GitHub Issues page

When submitting an issue, please provide as much detail as possible, including steps to reproduce, error messages, and your Unity and SDK versions.

Our Partner Success Team

For account-specific questions, strategic guidance, or high-priority support:

• Contact your dedicated account manager directly
• Or reach out to our partner success team at [email protected]

Our partner success team is committed to ensuring you get the most out of the Noctua SDK and can help with custom integrations, best practices, and optimization strategies.