Developers

Unity SDK

Load your Ava-Twin avatar into any Unity scene in minutes. The SDK handles customizer integration, GLB downloading, humanoid setup, animations, and caching.

v1.0.0Free plan available — no credit card required

Installation

Install via Unity Package Manager (UPM) using a Git URL:

1. In Unity, open Window → Package Manager.
2. Click + and select Add package from git URL…
3. Paste the following URL and click Add:

text

https://github.com/waqaszs/ava-twin-unity-sdk.git#v1.0.0

Dependencies: The SDK automatically resolves its dependencies via UPM: glTFast 5.2.0 and Newtonsoft.Json 3.2.1. No manual setup required.

Demo Scene

The SDK ships with a ready-to-play demo scene. After installing, open Window → Package Manager, select the Ava-Twin SDK, go to the Samples tab, and click Import next to Demo Scene.

Requirements: Unity 2021.3 LTS or later. .NET Standard 2.1. Supports WebGL, iOS, and Android (Desktop coming soon).

Quick Start

1. In Unity, go to Ava-Twin → Setup from the menu bar. Enter your App ID and API Key from your dashboard.
2. Call await SDK.OpenCustomizerAsync() to open the customizer and receive the avatar:

csharp

using AvaTwin;
using UnityEngine;

public class AvatarLoader : MonoBehaviour
{
    [SerializeField] private Transform playerTransform;
    [SerializeField] private Animator animator;

    async void Start()
    {
        var result = await SDK.OpenCustomizerAsync();
        if (result != null)
        {
            result.Root.transform.SetParent(playerTransform);

            var humanoid = result.GetUnityHumanoidAvatar();
            if (humanoid != null)
            {
                animator.avatar = humanoid;
                animator.Rebind();
            }
        }
    }
}

Security: Never hardcode API keys. Use a Credentials ScriptableObject and exclude it from version control via .gitignore.

API Reference

CharacterLoader — Methods

Methods

OpenCustomizer()

Open the customizer overlay (internal — use SDK.OpenCustomizerAsync() instead). WebGL: iframe. Mobile: native UI. Editor: loads a random avatar.

CloseCustomizer()

Close the customizer overlay.

LoadCharacterFromUrl(string url)

Load a character from a specific GLB URL.

LoadPreviewCharacterFromUrl(string url)

Load a preview character. Does not fire CharacterLoaded (fires CharacterVisualLoaded instead).

ResolveAndLoadAvatarDirect(string avatarId)

Resolve an avatar ID to a GLB URL via the API, then load it.

SetSkinToneHex(string hex)

Apply a skin tone to the loaded character. Hex format, e.g. "#C68642".

SetCredentials(string appId, string apiKey)

Override credentials at runtime instead of using the Inspector asset.

CancelLoad()

Cancel an in-progress avatar download.

GetLoadedCharacter()

Returns the loaded character GameObject, or null if none loaded.

GetLoadedCharacterAvatar()

Returns the humanoid Avatar asset from the loaded character.

CharacterLoader — Events

Advanced: These events are for advanced use cases (e.g. custom loading pipelines, progress tracking). For most scenarios, use SDK.OpenCustomizerAsync() or SDK.LoadAvatar() instead.

Events

CharacterLoaded

Action<GameObject> — fires when a character is fully loaded into the scene.

CharacterVisualLoaded

Action — fires on any visual load, including previews.

CharacterLoadFailed

Action<string> — fires on load error with a description of what went wrong.

CharacterLoader — Properties

Properties

GlbUrl (string)

Get or set the GLB URL. Setting this does not trigger a load automatically.

SkinToneHex (string)

Read-only. The current skin tone hex value.

IsCustomizerOpen (bool)

Read-only. Whether the customizer overlay is currently visible.

CharacterLoader — Inspector Fields

Inspector Fields

useCache (bool)

Enable local GLB caching. Default: true.

cacheTtlMinutes (float)

Minutes before a cached avatar is re-downloaded. Default: 60.

customizerUrl (string)

URL of the customizer page. Pre-filled with the Ava-Twin hosted customizer — only change this if you self-host.

credentials

Reference to a Credentials ScriptableObject that holds your App ID and API Key. Configure via Ava-Twin > Setup menu.

customizerAllowedOrigin

Advanced override. If your game uses a strict referrer policy that blocks document.referrer, set this to explicitly tell the SDK its parent origin (e.g. "https://yourgame.com"). Otherwise leave blank — the SDK detects automatically.

SDK — Static Methods

The SDK static class provides the primary async/await API for loading avatars. These are the recommended entry points for most use cases.

Static Methods

SDK.OpenCustomizerAsync()

Opens the customizer overlay and returns Task<AvatarResult>. Resolves when the user confirms their avatar. Returns null if the user cancels. Credentials are loaded automatically from the Credentials asset.

SDK.LoadAvatar(string avatarId, string skinToneHex = null)

Resolves an avatar ID to a GLB URL via the API, loads it, and returns Task<AvatarResult>. Optionally applies a skin tone. Credentials are loaded automatically from the Credentials asset.

Note: Credentials are loaded automatically from the Credentials asset (set up via Ava-Twin > Setup menu in Unity). No need to pass appId or apiKey as parameters.

csharp

using AvaTwin;
using UnityEngine;

public class QuickLoad : MonoBehaviour
{
    [SerializeField] private Animator animator;

    async void Start()
    {
        var result = await SDK.OpenCustomizerAsync();
        if (result != null)
        {
            result.Root.transform.SetParent(transform);

            var humanoid = result.GetUnityHumanoidAvatar();
            if (humanoid != null)
            {
                animator.avatar = humanoid;
                animator.Rebind();
            }
        }
    }
}

AvatarResult

Returned by SDK.OpenCustomizerAsync() and SDK.LoadAvatar(). Contains the instantiated avatar and metadata needed for animation, persistence, and networking.

Properties

Root (GameObject)

The instantiated avatar root GameObject in the scene.

AvatarId (string)

Opaque identifier for this avatar. Use for persistence (save/load) and network sync.

SkinToneHex (string)

The skin tone hex color applied to this avatar (e.g. "#C68642").

Methods

GetUnityHumanoidAvatar()

Returns the Unity Humanoid Avatar asset for Mecanim animation. Assign to Animator.avatar and call Rebind() to drive the avatar with your animation controller.

AvaTwinCharacterController

A third-person character controller included in the SDK demo. Drives a humanoid Animator with four parameters: Speed, Grounded, Jump, and FreeFall.

Public Fields

moveSpeed (float)

Walk speed in units/sec.

sprintSpeed (float)

Sprint speed in units/sec.

jumpHeight (float)

Jump height in units.

gravity (float)

Gravity strength (negative value).

AvaTwinInput

Input data struct consumed by AvaTwinCharacterController.

Fields

move (Vector2)

Movement input (WASD / left stick).

look (Vector2)

Camera look input (mouse / right stick).

jump (bool)

Jump input.

sprint (bool)

Sprint input.

Platform Notes

Supported platforms: WebGL, iOS, and Android. Desktop standalone (Windows, macOS, Linux) is currently blocked at the SDK level (SDK.cs CheckPlatformSupport) — Studio+ plan tier supports identifier registration, but full SDK support is coming.

WebGL

The customizer opens as an iframe overlay. The SDK uses postMessage for iframe communication.
Register your origin in Console (e.g. mygame.com or *.mygame.com). Local dev (localhost, 127.0.0.1) is auto-allowed.
Enable Brotli compression in Player Settings for smaller builds. Avatars are cached in IndexedDB across browser sessions.

Mobile (Android / iOS)

The customizer opens as a native in-app UI with category tabs (head, top, bottom, shoes), a skin tone picker, and a drag-to-rotate avatar preview. The mobile customizer prefab loads automatically from Resources — no Inspector configuration needed.
Register your Java package name (Android) or CFBundleIdentifier (iOS) in Console — must match your build's Application.identifier.
Same SDK.OpenCustomizerAsync() and SDK.LoadAvatar() API as WebGL. GLB downloads use UnityWebRequest (no CORS restrictions on native mobile).

Unity Editor

Calling SDK.OpenCustomizerAsync() in the Editor auto-loads a random avatar for quick iteration. No browser or iframe is opened.
Editor mode bypasses identifier checks — Console registration is not required for editor work.
Use LoadCharacterFromUrl() to test with a specific avatar.

Desktop standalone

Currently blocked at the SDK level (SDK.cs CheckPlatformSupport).
Studio+ plan tier supports identifier registration; full SDK support is coming.

Full setup guide at Registering Build Identifiers.

Troubleshooting

Problem

Character doesn’t appear after loading

Solution

Check the Console for errors. Verify CharacterLoader is on an active GameObject and the Credentials asset has a valid App ID and API Key.

Problem

"Not initialized" or credentials error

Solution

Configure your credentials via Ava-Twin > Setup in the menu bar with a valid App ID and API Key from your dashboard.

Problem

T-pose (no animations)

Solution

Ensure the SDK’s Animator Controller is in your project. If using a custom Animator, verify the clips use the correct humanoid avatar from AvatarResult.GetUnityHumanoidAvatar().

Problem

403 ORIGIN_NOT_REGISTERED

Solution

Your WebGL build's origin isn't registered. Open Console → Apps → [your app] → Edit → register your domain (e.g. "yourgame.com" or "*.yourgame.com"). See Registering Build Identifiers.

Problem

403 ORIGIN_NOT_ALLOWED

Solution

A registered origin exists but doesn’t match the browser’s Origin header. Check for typos and wrong subdomains. Wildcards: *.example.com matches subdomains but not the apex — register both if you need www and bare.

Problem

403 BUNDLE_NOT_ALLOWED

Solution

Your build’s Application.identifier doesn’t match a registered bundle ID. Verify Player Settings → Other Settings → Identification (Android package name / iOS bundle identifier) and register that exact value in Console.

Problem

403 PARENT_ORIGIN_REQUIRED

Solution

The customizer iframe couldn’t determine its parent origin. Your game’s referrer policy may be too strict — try "strict-origin-when-cross-origin" (the browser default). As an advanced override, set customizerAllowedOrigin on the CharacterLoader Inspector to your hosting domain.

Problem

Advanced: customizerAllowedOrigin override

Solution

The customizerAllowedOrigin Inspector field is no longer the primary mechanism — use Console identifier registration instead. Only set this field if a strict referrer policy blocks document.referrer; otherwise leave it blank and the SDK detects the parent origin automatically.

Problem

Works in Editor but not in WebGL build

Solution

The Editor bypasses identifier checks and auto-loads a random avatar. In WebGL, confirm your origin is registered in Console (Apps → Edit) and that the WebGL template is set to AvaTwin.

Problem

Slow first load

Solution

First loads download the GLB over the network (1–3s typical). Caching is on by default (useCache = true), so subsequent loads are near-instant.

For step-by-step setup, see Registering Build Identifiers.

Get the Unity SDK

Open Dashboard

← Getting Started REST API Reference →