Session API

GraffityARCloudSession is the component that connects your AR Foundation scene to Graffity AR Cloud. It owns one SDK facade, GraffityARCloud, exposed as session.sdk. Use the facade to observe state and guidance, and to navigate.

Call every API on the Unity main thread. Use one session per AR Session and XR Origin.

Inspector fields

The session reads these values once, when it initializes. To change them later, await session.shutdown(), edit them, and start again.

Configure from code

To keep the token out of your scene file, set it before the session initializes:

session.setAccessToken(tokenFromYourBackend);
session.start();

The SDK accepts the raw token or the Bearer <token> form. setAccessToken throws once the session is initialized.

To bind scene references from code, call configure before initialization:

session.configure(arSession, xrOrigin, new[] { mapRoot });

session.validateSetup() returns a list of setup problems without starting anything. An empty list means the setup is valid.

Lifecycle

The session pauses when the component is disabled or the app goes to the background, and resumes when it is back. A pause() you call yourself stays in effect until you call resume().

State

session.sdk.state is an immutable GraffityARState snapshot:

GraffityARVPSState.kind is one of:

There are three ways to observe state:

// 1. Observable: replays the current state, then each change.
IDisposable subscription = session.sdk.statePublisher.Subscribe(observer);
subscription.Dispose();
 
// 2. Async stream: skips intermediate states if you are slower than the SDK.
await foreach (var state in session.sdk.stateStream(cancellationToken)) { /* ... */ }
 
// 3. Delegate: see below.
session.sdk.@delegate = myDelegate;

Dispose every subscription. When the session shuts down, it sends a final idle state and then completes all observers.

Delegate

Derive from GraffityARCloudDelegateAdapter and override the callbacks you need:

using Graffity.ARCloud;
using UnityEngine;
 
public sealed class GameEvents : GraffityARCloudDelegateAdapter
{
    public override void didLocalizeIn(GraffityARCloud sdk, string sectionId)
        => Debug.Log("Localized in " + sectionId);
 
    public override void didArriveAt(GraffityARCloud sdk, GraffityARDestination destination)
        => Debug.Log("Arrived at " + destination.displayName);
 
    public override void didFailWith(GraffityARCloud sdk, GraffityARCloudError error)
        => Debug.LogWarning("Graffity error: " + error.code);
}
 
// After start():
session.sdk.@delegate = new GameEvents();

The SDK keeps a strong reference to the delegate until you replace it or the session shuts down. delegate is a C# keyword, so write it as @delegate.

Localization guidance

During active localization, session.sdk.localizationGuidance (and guidancePublisher) tells you what to ask the player to do:

targetPose is a 4×4 column-major matrix in the XR Origin’s tracking space (the camera’s parent, session.trackingOrigin). It uses Unity’s convention. To show a marker the player should aim at:

var g = session.sdk.localizationGuidance;
if (g.targetPose != null)
{
    var m = g.targetPose.m;
    var position = new Vector3(m[12], m[13], m[14]);
    var forward  = new Vector3(m[8],  m[9],  m[10]);
    marker.transform.SetParent(session.trackingOrigin, false);
    marker.transform.localPosition = position + forward * 1.5f;   // aim point in front of the target
}

The Host integration sample includes a complete guidance view, ActiveLocGuidanceView, and an overlay, VPSOverlayController, with English and Thai text.

Errors

GraffityARCloudError has a stable code that you can switch on. Errors arrive in state.lastError and didFailWith.

Scripts without the component

new GraffityARCloud(new GraffityARCloudConfiguration(accessToken)) creates a facade without a scene. You can use it to read state, but it has no camera input, so it can’t localize or navigate. Use GraffityARCloudSession for AR, and call shutdown() on any facade you create yourself.

Analytics and diagnostics

Built-in analytics are off by default. Enter an Analytics Project Key in the session Inspector to send session, localization and navigation events. No key ships with the package.

To route SDK diagnostics to your own logger, implement GraffityARDiagnosticLogger and call session.sdk.setDiagnosticLogger(logger). Diagnostics never include tokens or camera images.