Unity

Integrate OnsideKit into a Unity game targeting iOS with the OnsideKit Unity package — a C# wrapper over the native SDK.

The OnsideKit Unity package lets you use OnsideKit from C# in a Unity game that ships to iOS. It is a thin wrapper over the native OnsideKit iOS SDK: your C# calls are forwarded to the native SDK, and native events are delivered back to C#. The same concepts apply — products, the payment queue, transactions, login, attribution, and event tracking — so the Core Concepts and Error Reference pages are good companion reading.

• Package: io.onside.onsidekit-unity

• Namespace: OnsideKit

• Requires: Unity 2022.1+, an iOS build target

The native bridge exists only in an iOS device/simulator build. In the Unity Editor (and on non-iOS platforms) the API calls are no-ops, so you test the actual purchase flow by building and running on iOS.

1. Install the package

Download OnsideKit-Unity-<version>.unitypackage from the Releases of the OnsideKit-iOS repository. In Unity, choose Assets → Import Package → Custom Package, select the file, and click Import All.

The External Dependency Manager (EDM4U) is bundled in the package, and the native OnsideKit SDK is pulled in automatically when you build for iOS — you don't need to add any scoped registries or extra dependencies.

2. Create the settings asset

In Unity: Assets → Create → OnsideKit → Settings.

This creates Assets/OnsideKit/Resources/OnsideKitSettings.asset. Set:

• Callback Scheme (required) — your app's unique URL scheme (e.g. myapp-onside). It must match the scheme you pass to Onside.Initialize(...), and the iOS build fails if it's empty. The Onside Store app uses it to return to your game after login/payment.

• StoreKit Configuration Path (optional) — path to a .storekit file for offline local testing. The file is copied into the generated Xcode project.

3. Write your integration

using System.Collections.Generic;
using OnsideKit;
using UnityEngine;

public class StoreManager : MonoBehaviour, IOnsidePaymentTransactionObserver
{
    void Start()
    {
        // 1. Initialize once. Use the same scheme as in OnsideKitSettings.
        Onside.Initialize("myapp-onside");

        // 2. Subscribe to product events and register as a transaction observer.
        var queue = Onside.DefaultPaymentQueue;
        queue.ProductsReceived += OnProductsReceived;
        queue.ProductsRequestFailed += error => Debug.LogError($"Products failed: {error}");
        // The only signal that an Add(payment) was rejected before a transaction
        // was created (e.g. the user dismissed login).
        queue.AddPaymentFailed += (productId, error) =>
            Debug.LogWarning($"Purchase rejected: {productId} — {error}");
        queue.Add(this);

        // 3. Fetch products.
        queue.RequestProducts(new List<string> { "premium_feature", "remove_ads" });
    }

    void OnProductsReceived(IList<OnsideProduct> products, IList<string> invalidIdentifiers)
    {
        foreach (var p in products)
            Debug.Log($"{p.localizedTitle} — {p.price.value} {p.price.currencyCode}");
    }

    // Start a purchase (e.g. from a Buy button).
    public void Buy(string productIdentifier)
    {
        Onside.DefaultPaymentQueue.Add(new OnsidePayment(productIdentifier));
    }

    // --- IOnsidePaymentTransactionObserver ---

    public void OnsidePaymentQueueUpdatedTransactions(
        OnsidePaymentQueue queue, IList<OnsidePaymentTransaction> transactions)
    {
        foreach (var t in transactions)
        {
            switch (t.State)
            {
                case OnsidePaymentTransactionState.Purchased:
                case OnsidePaymentTransactionState.Restored:
                    UnlockContent(t.productIdentifier);
                    queue.FinishTransaction(t);   // required
                    break;
                case OnsidePaymentTransactionState.Failed:
                    Debug.LogWarning($"Purchase failed: {t.Error}");
                    queue.FinishTransaction(t);   // required
                    break;
                case OnsidePaymentTransactionState.Purchasing:
                    break;   // in progress — wait
            }
        }
    }

    void UnlockContent(string productIdentifier) { /* grant + persist */ }

    public void OnsidePaymentQueueRemovedTransactions(
        OnsidePaymentQueue queue, IList<OnsidePaymentTransaction> transactions) { }
    public void OnsidePaymentQueueRestoreCompletedTransactionsFinished(
        OnsidePaymentQueue queue) { }
    public void OnsidePaymentQueueRestoreCompletedTransactionsFailed(
        OnsidePaymentQueue queue, OnsideTransactionsRestoreError error) { }
    public void OnsidePaymentQueueDidChangeStorefront(
        OnsidePaymentQueue queue) { }
}

Key rules

• Callbacks run on Unity's main thread — you can safely touch Unity APIs inside them.

• Finish every transaction — call FinishTransaction for each Purchased, Restored, or Failed transaction, or it is re-delivered on the next launch.

• AddPaymentFailed is the only signal that an Add(payment) was rejected before a transaction was created (e.g. the user dismissed login). The transaction observer is not called in that case.

• The Editor is a no-op — methods and callbacks run only in an on-device iOS build (outside it you get a warning and callbacks don't fire). Test on a device/simulator.

• ShouldContinueHandler must return quickly — the native purchase flow blocks waiting for its answer.

4. Build for iOS

1. File → Build Settings → iOS → Switch Platform, then Build.

2. A post-process build step runs automatically and configures the generated Xcode project: it embeds OnsideKit.framework, adds onside to LSApplicationQueriesSchemes, registers your callback scheme under CFBundleURLTypes, copies your .storekit file (if set), and applies the required Swift/build settings.

3. Open the generated .xcodeproj and run on a device (or the simulator).

You don't need to edit the Xcode project or Info.plist by hand, and you don't implement any URL handling yourself — incoming URLs are caught automatically by the bundled app controller.

How it works

Your C# calls are marshaled to the native SDK; native events are delivered back to a persistent OnsideKit GameObject (created by Initialize) via UnitySendMessage and surfaced as C# events/observer callbacks.

Onside.Initialize("myapp-onside")
  → creates the persistent "OnsideKit" GameObject
  → native [Onside initialize] + callbackScheme + delegate/observer wiring

DefaultPaymentQueue.RequestProducts(ids)
  → native OnsideProductsRequest → products serialized to JSON
  → C# OnsidePaymentQueue.ProductsReceived fires

DefaultPaymentQueue.Add(payment)
  → native purchase flow (may open the Onside Store app)
  → Store app returns via myapp-onside:// → native handleURL
  → transaction updates → IOnsidePaymentTransactionObserver

---

API Reference

Onside (static)

static void Initialize(string callbackScheme, string storeKitConfigurationName = null)

Initializes the SDK and creates the persistent OnsideKit GameObject. Call once at startup, before any other call. Idempotent — a second call is ignored. storeKitConfigurationName enables offline local testing.

Member	Description
OnsidePaymentQueue DefaultPaymentQueue { get; }	The shared payment queue.
void RequestLogin(Action onSuccess = null, Action<OnsideLoginError> onFailed = null)	Present the login flow. Login is also triggered on demand by a purchase or by presenting the payment methods manager.
void Logout()	End the current session.
void SetThemeMode(OnsideUIThemeMode mode)	Global theme: Auto, Light, or Dark.
void SetDelegateOptions(string countryCodeHint = null, bool forceLocalLoginMethods = false)	Pre-login region hint and force the in-app login screen. See The Onside Delegate.
void SetApplePayMerchantIdentifier(string merchantIdentifier)	Configure Apple Pay. No-op if the SDK build has no Apple Pay. See Apple Pay.
void PresentPaymentMethodsManager(Action onSuccess = null, Action<OnsidePaymentMethodsManagerError> onFailed = null)	Show the saved-cards manager.
void GetAttributionMetadata(Action<OnsideAttributionMetadata> onSuccess = null, Action<OnsideAttributionMetadataError> onFailed = null)	Fetch attribution metadata.
void Track(string eventName, Dictionary<string, object> parameters = null)	Send an analytics event. See Event tracking.
void ResetLocalTestingState()	Reset local-testing purchase history.

Signed in-app purchase history — subscribe to the static events, then request:

static event Action<OnsideSignedInAppsHistory> SignedInAppsHistoryReceived;
static event Action<OnsideSignedInAppsHistoryRequestError> SignedInAppsHistoryFailed;
static event Action SignedInAppsHistoryFinished;

static void RequestSignedInAppsHistory();
static void StopSignedInAppsHistoryRequest();

See Signed In-App Purchase History.

Installation id — for support/diagnostics (see Debugging):

static string InstallationId { get; }
static event Action<string> InstallationIdChanged;   // may deliver null while loading
static void SubscribeInstallationId();               // call once to start receiving

OnsidePaymentQueue

Accessed via Onside.DefaultPaymentQueue.

OnsideStorefront Storefront { get; }                  // null until logged in
IList<OnsidePaymentTransaction> Transactions { get; } // snapshot of current transactions

event Action<IList<OnsideProduct>, IList<string>> ProductsReceived;  // (products, invalidIdentifiers)
event Action<OnsideProductsRequestError> ProductsRequestFailed;
event Action ProductsRequestFinished;
event Action<string, OnsidePaymentQueueAddProductError> AddPaymentFailed;  // (productIdentifier, error)

// Optional storefront/price-change gate. Return false to cancel a transaction
// whose storefront changed. Keep it fast; if null, transactions always continue.
Func<OnsidePaymentTransaction, OnsideStorefront, bool> ShouldContinueHandler;

void RequestProducts(IList<string> productIdentifiers);
void Add(OnsidePayment payment);
void FinishTransaction(OnsidePaymentTransaction transaction);
void RestoreCompletedTransactions(Action<bool> completion = null);

void Add(IOnsidePaymentTransactionObserver observer);     // replays current transactions
void Remove(IOnsidePaymentTransactionObserver observer);

The ShouldContinueHandler is the Unity equivalent of the native storefront safety gate — see Handling Storefront & Price Changes.

IOnsidePaymentTransactionObserver

Method	When
OnsidePaymentQueueUpdatedTransactions(queue, transactions)	Transactions added or changed state. Finish each completed one.
OnsidePaymentQueueRemovedTransactions(queue, transactions)	Transactions removed (after finishing).
OnsidePaymentQueueRestoreCompletedTransactionsFinished(queue)	A restore finished successfully.
OnsidePaymentQueueRestoreCompletedTransactionsFailed(queue, error)	A restore failed.
OnsidePaymentQueueDidChangeStorefront(queue)	The storefront changed (login/logout/region).

Types

class OnsidePayment {
    string productIdentifier { get; }
    string appAccountToken { get; }   // optional, ties the purchase to your account
    OnsidePayment(string productIdentifier, string appAccountToken = null);
}

enum OnsidePaymentTransactionState { Unknown = -1, Purchasing = 0, Purchased = 1, Restored = 2, Failed = 3 }

class OnsidePaymentTransaction {
    string id;
    string transactionIdentifier;
    string originalTransactionIdentifier;
    string productIdentifier;
    string appAccountToken;
    OnsideStorefront storefront;
    OnsidePaymentTransactionState State { get; }
    OnsidePaymentTransactionError? Error { get; }   // set only when Failed
}

class OnsideProduct {
    string productIdentifier;
    string localizedTitle;
    string localizedDescription;
    OnsidePrice price;          // value (double) + currencyCode (string)
    string iconUrl;
    string subscriptionGroupIdentifier;   // subscriptions only; null otherwise
    OnsidePeriod subscriptionPeriod;      // subscriptions only; null for one-time products
}

class OnsidePeriod { string unit; long value; }   // unit: "day" | "week" | "month" | "year"

class OnsideStorefront { string id; string countryCode; }

class OnsideAttributionMetadata { string refererUrl; }

class OnsideSignedInAppsHistory {
    string Text { get; }    // decoded UTF-8 payload
    byte[] Bytes { get; }   // decoded raw bytes
}

enum OnsideUIThemeMode { Auto = 0, Light = 1, Dark = 2 }

The subscription fields on OnsideProduct (the billing period and group) carry the same meaning as in the native SDK — see Subscriptions.

Errors

All error enums include an Unknown fallback. Notable cases:

Enum	Cases
OnsideProductsRequestError	Cancelled, ConnectionError, AppNotRegistered, InvalidProductIdentifier, ServiceUnavailable, InternalError
OnsidePaymentQueueAddProductError	LoginDiscarded
OnsideTransactionsRestoreError	Cancelled, ConnectionError, AppNotRegistered, ServiceUnavailable, InternalError, LoginDiscarded
OnsidePaymentTransactionError	Cancelled, PresentationFailed
OnsideLoginError	LoginDiscarded, RequestAlreadyInProgress
OnsidePaymentMethodsManagerError	LoginDiscarded, NotSupportedInLocalTesting, RequestAlreadyInProgress
OnsideAttributionMetadataError	ConnectionError, AppNotRegistered, ServiceUnavailable, InternalError, RequestAlreadyInProgress
OnsideSignedInAppsHistoryRequestError	NotLoggedIn, NotSupportedInLocalTesting, Cancelled, ConnectionError, AppNotRegistered, ServiceUnavailable, InternalError

The meaning of each case matches the native SDK — see the Error Reference. The RequestAlreadyInProgress cases are Unity-specific: they're returned when you start a one-shot request (login, payment methods, attribution) while a previous one is still pending.

Common issues

Issue	Fix
Callback scheme doesn't work	Ensure the Callback Scheme in OnsideKitSettings matches the string passed to Onside.Initialize().
Products request returns nothing	Check that your product identifiers match what's configured in the Onside Developer Console.
Nothing happens in the Editor	Expected — the native bridge only runs in an iOS build. Test on a device/simulator.