Unity SDK Setup

The FirstLook Unity SDK lets you interface with FirstLook from your Unity game. The SDK supports Steam and Google Play authentication, in-game surveys, session tracking, custom events, and custom duration events.

The SDK ships as two Unity packages:

• com.pragma.firstlook.core is the required runtime package for authentication, sessions, analytics, and survey transport.
• com.pragma.firstlook.ui is an optional native survey UI package built on top of core.

The main integration surface is FirstLookClient, which you initialize through FirstLookBootstrap.InitializeWithSettings(...). If you install the UI package, FirstLookSurveyPresenter is the main packaged entry point for native in-game survey rendering.

For this setup guide, we will assume you have a Unity project named MyGame.

Prerequisites

Steam

1. Acquire the FirstLook Unity SDK from the admin dashboard.

2. Set up your Steam game in FirstLook. See the Steam Integration.

3. Invite a test player to your playtest with their Steam account linked. See the Inviting Players.

4. Collect the values you’ll need for setup:

   • gameSlug from your FirstLook game settings
   • clientUrl from your FirstLook domain settings
   • Your Steam App ID

   To find your client URL, check your domain from your FirstLook settings:

Google Play

1. Acquire the FirstLook Unity SDK from the admin dashboard.

2. Set up Google Play in FirstLook. See the Google Play Integration guide for how to configure your closed testing track, create the required OAuth 2.0 credentials, and add your client ID to FirstLook.

   Specifically, you need a Web application OAuth 2.0 client ID (not an Android client ID) added to Config > Google Play in your FirstLook dashboard. You will also need an Android OAuth client registered with your app’s package name and SHA-1 fingerprint so Google accepts sign-in requests from your build.

3. Collect the values you’ll need for setup:

   • gameSlug from your FirstLook game settings
   • clientUrl from your FirstLook domain settings

Installing the FirstLook Unity packages

Now that you’ve acquired the FirstLook Unity SDK and set up your game in FirstLook, install the packages into your Unity project.

1. Unzip FirstLookUnitySdk.zip (the file you downloaded from the admin dashboard) to extract the com.pragma.firstlook.core and com.pragma.firstlook.ui package tarballs.

2. Open Window > Package Manager in the Unity Editor.

3. Select + > Add package from tarball... and install the com.pragma.firstlook.core tarball you extracted from the zip. This is the required package.

4. Repeat the same Add package from tarball... flow for com.pragma.firstlook.ui if you want the packaged native in-game survey UI. If you plan to render survey UI yourself, you can skip this package.

5. Add your platform authentication dependency:

   Steam

   Add Steamworks.NET to Packages/manifest.json.

   {
     "dependencies": {
       "com.rlabrecque.steamworks.net": "https://github.com/rlabrecque/Steamworks.NET.git?path=/com.rlabrecque.steamworks.net#2025.163.0"
     }
   }

   Unity automatically defines FIRSTLOOK_STEAMWORKS when Steamworks.NET is installed, which enables FirstLookSteamHelper.

   Google Play

   The FirstLook SDK accepts a raw Google ID token, so you can use any Google Sign-In library that provides one — for example, the Google Play Games Plugin for Unity or the Google Sign-In Unity Plugin.

   Install your preferred Google Sign-In library and configure it with the Web application client ID you added to your FirstLook dashboard. This must be the same client ID — it is used to both initiate sign-in and verify the resulting ID token.

   Once the user signs in, retrieve the ID token from the library and pass it to AuthenticateWithGoogle(idToken). The exact API varies by library:

   • Google Play Games Plugin: configure RequestIdToken = true in PlayGamesClientConfiguration, then retrieve the token with ((PlayGamesLocalUser)Social.localUser).GetIdToken() after sign-in.
   • Google Sign-In Unity Plugin: after GoogleSignIn.DefaultInstance.SignIn() resolves, read GoogleSignInUser.IdToken from the result.

   Refer to your chosen library’s documentation for the full sign-in setup.

Configuring FirstLookSettings

The Unity SDK reads configuration from a FirstLookSettings asset.

1. Create Assets/Resources/FirstLookSettings.asset in the Unity Editor:

   • Assets > Create > FirstLook > Settings

2. Configure the required fields on the asset:

   • apiUrl: https://api.firstlook.gg
   • clientUrl: https://<game-slug>.firstlook.gg
   • gameSlug: your FirstLook game slug
   • buildVersion: optional build label attached to analytics events

3. Leave the retry, queue, and logging settings at their defaults unless your project needs different behavior.

FirstLookBootstrap and FirstLookSurveyPresenter can both resolve Resources/FirstLookSettings automatically when it is present.

clientUrl is only required if you plan to open browser-delivered surveys through ActivateSurveyBrowserOverlay(...).

Authentication bootstrap

The preferred Unity integration path is host-owned bootstrap. Initialize FirstLook once, authenticate with your platform, and start the session explicitly.

Steam

Make sure Steamworks has already been initialized, then authenticate and start the session.

using Pragma.FirstLook;
using UnityEngine;

public sealed class FirstLookStartup : MonoBehaviour
{
    [SerializeField] private FirstLookSettings firstLookSettings;

    private FirstLookClient _client;

    private async void Start()
    {
        var settings = firstLookSettings != null
            ? firstLookSettings
            : Resources.Load<FirstLookSettings>("FirstLookSettings");

        if (settings == null)
        {
            Debug.LogError("[FirstLookStartup] Missing FirstLookSettings.");
            return;
        }

        _client = FirstLookBootstrap.InitializeWithSettings(settings);

#if FIRSTLOOK_STEAMWORKS
        var ticket = FirstLookSteamHelper.GetSessionTicket();
        if (string.IsNullOrWhiteSpace(ticket))
        {
            Debug.LogError("[FirstLookStartup] Steam ticket unavailable. Make sure Steamworks is initialized first.");
            return;
        }

        var result = await _client.AuthenticateAndStartSessionAsync(
            FirstLookAuthRequest.Steam(ticket, FirstLookSteamHelper.GetAppId()));

        if (!result.Success)
        {
            Debug.LogError($"[FirstLookStartup] FirstLook startup failed: {result.AuthResult?.Error}");
            return;
        }

        Debug.Log($"[FirstLookStartup] FirstLook ready. Session: {result.SessionId}");
#else
        Debug.LogError("[FirstLookStartup] Steamworks.NET is not installed.");
#endif
    }
}

Quick Validation

FirstLookAutoLifecycle is available for quick validation or simple scenes, but it is a convenience path. For production Steam integrations, prefer explicit host-owned startup like the example above.

Google Play

Use your Google Sign-In library to obtain a Google ID token, then pass it to FirstLook.

using Pragma.FirstLook;
using UnityEngine;

public sealed class FirstLookStartup : MonoBehaviour
{
    [SerializeField] private FirstLookSettings firstLookSettings;

    private FirstLookClient _client;

    // Call this once you have obtained a Google ID token from your
    // Google Sign-In library (e.g. Google Play Games Plugin or Google Sign-In Unity Plugin).
    public async void AuthenticateWithGoogle(string googleIdToken)
    {
        var settings = firstLookSettings != null
            ? firstLookSettings
            : Resources.Load<FirstLookSettings>("FirstLookSettings");

        if (settings == null)
        {
            Debug.LogError("[FirstLookStartup] Missing FirstLookSettings.");
            return;
        }

        _client = FirstLookBootstrap.InitializeWithSettings(settings);

        if (string.IsNullOrWhiteSpace(googleIdToken))
        {
            Debug.LogError("[FirstLookStartup] Google ID token was empty.");
            return;
        }

        var result = await _client.AuthenticateAndStartSessionAsync(
            FirstLookAuthRequest.GoogleIdToken(googleIdToken));

        if (!result.Success)
        {
            Debug.LogError($"[FirstLookStartup] FirstLook startup failed: {result.AuthResult?.Error}");
            return;
        }

        Debug.Log($"[FirstLookStartup] FirstLook ready. Session: {result.SessionId}");
    }
}

ID Token Source

FirstLookAuthRequest.GoogleIdToken(...) accepts any valid Google ID token. How you obtain the token depends on your Google Sign-In library. Refer to your library’s documentation for the sign-in flow and how to retrieve the ID token string.

Testing login

Steam

Now that the Unity SDK is installed and configured, test the Steam integration locally.

Steam Integration Testing

Steam authentication in Unity requires Steamworks.NET to be initialized before you call FirstLookSteamHelper.

Additionally, ensure that you have the following Steam setup:

• The Steam client is running.
• You are logged in with the Steam account you linked to your test player.
• The Steam account has the configured Steam app in its library.
• A steam_appid.txt file exists in your Unity project root and contains your Steam App ID.

1. Initialize Steamworks before your FirstLook startup code runs.

   • For example, add a scene object that calls SteamAPI.Init() in Awake() before any call to FirstLookSteamHelper.GetSessionTicket().

2. Press Play in the Unity Editor or run a development build.

3. In the Unity Console, confirm a successful startup log from your bootstrap code.

   • e.g. [FirstLookStartup] FirstLook ready. Session: 8c3b8f66-...

4. If Steam setup is incomplete, expect one of these failure signals instead:

   • [SteamManager] SteamAPI.Init() failed...
   • [FirstLookStartup] Steam ticket unavailable...
   • [FirstLookStartup] FirstLook startup failed: ...

Google Play

Test the Google Play integration on a device or emulator with Google Play Services.

Google Play Testing

Google ID token authentication requires a valid token signed by Google. Ensure that:

• Your Google client ID is added to the Config > Google Play allowed list in the FirstLook dashboard.
• The client ID used to sign in matches one in the allowed list.
• Your Google Sign-In library is initialized before calling AuthenticateWithGoogle(...).

1. Initialize your Google Sign-In library and trigger the sign-in flow to obtain a Google ID token.

2. Pass the token to AuthenticateWithGoogle(idToken) in your bootstrap code.

3. In the Unity Console, confirm a successful startup log.

   • e.g. [FirstLookStartup] FirstLook ready. Session: 8c3b8f66-...

4. If authentication fails, expect one of these signals:

   • [FirstLookStartup] Google ID token was empty.
   • [FirstLookStartup] FirstLook startup failed: Invalid Google ID token: ...

Session Tracking Labs

The Unity SDK does not start sessions just by being installed. A session begins when your host calls StartSessionAsync() or uses AuthenticateAndStartSessionAsync(...) successfully.

Once started, the SDK tracks the active session until you end it or the app shuts down. Internally, FirstLookRuntimeDriver attempts to call EndSessionAsync() on application quit as a best-effort graceful shutdown. Players who haven’t created a FirstLook account yet are still tracked — they’ll appear as Unlinked players in your dashboard, with their platform account associated.

Crash Handling

If the client crashes, no end time is recorded for that session. Incomplete sessions are excluded from average, top percentile, and rolling two-week session calculations to keep your metrics accurate.

Once sessions are being recorded, you’ll see player activity and session duration data on the Analytics page under the Retention tab, as well as on each individual Player Profile.

Custom Events Labs

Beyond session tracking, you can instrument your own gameplay events to capture whatever matters most to your studio — hero selections, match outcomes, store purchases, and more. Use PostCounterEventAsync(...) on FirstLookClient to send a named counter with an integer value:

public async void HandleHeroSelected()
{
    if (_client == null || !_client.IsSessionActive)
        return;

    await _client.PostCounterEventAsync("loadout.hero-a-selected", 1);
}

Naming and Grouping Events

Event names follow a <category>.<event-type> convention. When you use this pattern, FirstLook will automatically group related events together on the Analytics page and on Player Profiles, making it easy to browse metrics by category.

Choose a category namespace that reflects where the event occurs in your game — for example, match, lobby, menu, store, or in-game. You’re free to define as many categories as you need.

Caution

The firstlook namespace is reserved for built-in FirstLook events. Avoid using it for your own custom events.

Custom Duration Events Labs

Counter events record that something happened, but sometimes you need to know how long something took. Duration events let you measure elapsed time between two explicit points in your game — a match, a loading screen, time spent in a menu, or any other span you want to track.

Call StartDurationEventAsync(...) when the activity begins and EndDurationEventAsync(...) when it finishes. The SDK handles timing and delivery — you just provide a name.

public async void OnMatchStart()
{
    if (_client == null || !_client.IsSessionActive)
        return;

    await _client.StartDurationEventAsync("match.round");
}

public async void OnMatchEnd()
{
    if (_client == null || !_client.IsSessionActive)
        return;

    await _client.EndDurationEventAsync("match.round");
}

Naming and Grouping Events

Duration event names follow the same <category>.<event-type> convention as counter events. FirstLook automatically groups them by category prefix on the Analytics page.

Graceful Shutdown

If the game client shuts down before EndDurationEventAsync(...) is called, the duration event is left open and excluded from aggregate metrics — the same way incomplete sessions are handled.

Caution

The firstlook namespace is reserved for built-in events. Avoid using it for your own duration events.

Testing out In-Game Surveys

Once login and session startup are working, you can trigger in-game surveys from Unity.

In-Game Surveys Learn more about survey creation and trigger configuration

1. Create a survey with game client distribution enabled. See the Creating a Survey.

2. Set up a trigger for your newly created survey. See the Setting Up Triggers.

3. If you want the packaged native survey UI, install com.pragma.firstlook.ui and add a FirstLookSurveyPresenter with a FirstLookSurveyCanvas to your scene.

   • FirstLookSurveyPresenter subscribes to OnNewNativeSurveyAvailable, caches the active survey, and can reopen it through TryShowCurrentSurvey().

   • Start from the packaged survey prefabs, skins, and theme assets that ship with the UI package, then duplicate them into your project if you want to customize them.

4. If you want browser-delivered surveys, subscribe to OnNewBrowserSurveyAvailable in your host code and call ActivateSurveyBrowserOverlay(surveyUuid).

   • The shipped Unity UI package does not auto-open browser-delivered surveys for you.

5. Trigger the survey from your game:

   await _client.PostSurveyTriggerEventAsync("match.completed");

If you are building fully custom survey UI, you can skip com.pragma.firstlook.ui entirely and subscribe to the core survey events on FirstLookClient directly.