Unreal SDK Setup

The FirstLook Unreal SDK is an Unreal Engine plugin that will allow you to interface with FirstLook from your Unreal game. The plugin currently supports Steam login, in-game surveys, session tracking, custom events, custom duration events, player lookup, PlayFab identity linking, entitlements, and playtest watermarking. The primary access point for the FirstLook SDK is the UFirstLookSubsystem which exposes a number of methods and delegates used to interact with FirstLook.

For this setup guide, we will assume you have an Unreal game project named MyGame.

Learn More about Unreal Subsystems Unreal Documentation

Prerequisites

1. Acquire the FirstLookSDK from the admin dashboard.

2. Generate Unreal SDK configs.
3. Setup your Steam game in FirstLook. See the Steam Integration.

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

Setting up the FirstLookSDK Plugin in Unreal

Now that you’ve acquired the FirstLookSDK and set up your game in FirstLook, we can install the plugin into your Unreal project.

1. Move the FirstLookSDK plugin to MyGame/Plugins/FirstLookSDK. Create the MyGame/Plugins directory if one does not already exist.

2. Register the FirstLookSDK plugin in the MyGame.uproject file.

   "Plugins": [
     {
       "Name": "FirstLookSDK",
       "Enabled": true
     }
   ]

3. Add the FirstLookSDK plugin as a dependency in the MyGame.Build.cs file.

   PrivateDependencyModuleNames.AddRange(new string[] {"FirstLookSDK"});

4. In the Unreal Editor, configure the FirstLookSDK plugin settings for FirstLookApiURL, FirstLookClientURL, and FirstLookGameSlug under:

   Edit > ProjectSettings > Plugins > FirstLook

   • Alternatively, configure the plugin in the DefaultGame.ini file:

     [/Script/FirstLookSDK.FirstLookSDKSettings]
     FirstLookApiURL="https://api.firstlook.gg"
     FirstLookClientURL="https://<game-slug>.firstlook.gg"
     FirstLookGameSlug="<game-slug>"

     (Replace <game-slug> with your FirstLook game slug)

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

5. Configure OnlineSubsystemSteam in the DefaultEngine.ini file.

   [OnlineSubsystem]
   DefaultPlatformService=Steam
   
   [OnlineSubsystemSteam]
   bEnabled=true
   SteamDevAppId=<steam-app-id>

   (Replace <steam-app-id> with your Steam app ID)

   The SDK reads the Steam app ID from the running Steam client, falling back to SteamDevAppId only when Steam is unavailable. A single packaged build can therefore be shipped against multiple Steam app IDs, it reports whichever app the player actually launched. SteamDevAppId is still required so OnlineSubsystemSteam can initialise, and it remains the value used in the editor.

6. Setup Unreal CommonUI.

   • Follow Step 1 of this guide to set the default Game Viewport Client Class to CommonGameViewportClient.

Testing out FirstLook Steam Login

Now that the FirstLookSDK Unreal plugin is properly setup, FirstLook Steam login will work out of the box since it is automatically called during the FirstLook subsystem initialization. There are just a few steps we need to take in order to test the integration locally.

Steam Integration Testing

Steam integration with Unreal only works in packaged builds and standalone game mode.

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.

1. In the Unreal Editor, enable logging for Standalone Game mode

   • Under Edit > Editor Preferences, navigate to:

     Level Editor > Play > Play in Standalone Game > Additional Launch Parameters

   • Add -log as a launch parameter

   

2. Play as Standalone Game

3. In the output log, you should see log line indicating a successful login from the LogFirstLookSDK log category

   • e.g. LogFirstLookSDK: Verbose: Login succeeded.

Authentication State

The subsystem authenticates once, while it initializes: with Steam when a Steam ticket and app ID are available, otherwise anonymously. Calls made before authentication finishes are not queued. The SDK skips them and logs a single warning:

LogFirstLookSDK: Warning: FirstLook is not authenticated yet; <url> was skipped. Wait for OnFirstLookReady before calling the SDK.

A skipped call usually gets no reply, so its delegate never fires. A few calls answer immediately instead, so bind their delegates before calling: entitlement calls fire their failure delegate with 401 and Not authenticated, and PostEvent, GetFeedbackSurvey, and GetTriggeredSurveys report no survey available.

If authentication fails, the SDK logs that every FirstLook API call is skipped for this session and fires OnAuthenticationFailed. A failed login lasts until the game restarts.

C++

OnFirstLookReady and OnAuthenticationFailed are native events, so bind them with AddUObject or AddLambda. Each fires once, so check IsAuthenticated() and HasAuthenticationFailed() first in case authentication finished before you bound.

void UMainMenu::NativeConstruct()
{
    Super::NativeConstruct();

    if (UFirstLookSubsystem* FirstLook = GetOwningLocalPlayer()->GetSubsystem<UFirstLookSubsystem>())
    {
        if (FirstLook->IsAuthenticated())
        {
            HandleFirstLookReady();
        }
        else if (FirstLook->HasAuthenticationFailed())
        {
            HandleFirstLookFailed();
        }
        else
        {
            FirstLook->OnFirstLookReady.AddUObject(this, &UMainMenu::HandleFirstLookReady);
            FirstLook->OnAuthenticationFailed.AddUObject(this, &UMainMenu::HandleFirstLookFailed);
        }
    }
}

Blueprint

Call Is Authenticated before any FirstLook node, and Has Authentication Failed to tell “not yet” apart from “failed for this session”. The ready and failed events are C++ only.

Testing out In-Game Surveys

Now that you are able to successfully login to FirstLook, you will be able to use the FirstLook subsystem to trigger in-game surveys.

In-Game Surveys Learn more about In-Game Survey Integration

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

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

3. Register the survey delegates in Unreal:

   UFirstLookSubsystem::OnNewNativeSurveyAvailable:

   • The WBP_Survey_Screen widget should be displayed when this delegate is called. This widget can be found under: MyGame/Plugins/FirstLookSDK/Content/UI_Survey/Widgets/WBP_Survey_Screen.uasset

   UFirstLookSubsystem::OnNewBrowserSurveyAvailable:

   • Hooked up by default to show a Steam browser overlay using UFirstLookSubsystem::ActivateSurveyBrowserOverlay

4. Make a call to UFirstLookSubsystem::PostEvent with the trigger you created for your survey. If the trigger condition is met, this will trigger one of the delegates that we setup in the previous step depending on the configured survey distribution channel.

Sessions and Events

Session Tracking

The FirstLook SDK automatically tracks player sessions without any additional code on your part. A session begins when the UFirstLookSubsystem initializes, and ends when the game client shuts down gracefully. Players who haven’t created a FirstLook account yet are still tracked — they’ll appear as Unlinked players in your dashboard, with their Steam account associated if they’re signed in.

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

Beyond automatic 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 the PostCounterEvent method on the UFirstLookSubsystem to send a named counter with an integer value:

UCLASS()
class FIRSTLOOKSDK_API UFirstLookSubsystem : public ULocalPlayerSubsystem
{
public:
    // ...
    UFUNCTION(BlueprintCallable, Category = FirstLook)
    void PostCounterEvent(FString CounterName, int32 Count);

    UFUNCTION(BlueprintCallable, Category = FirstLook)
    void PostCounterEventWithParam(FString CounterName, FString Param, int32 Count);
    // ...
}

Example

Below is an example of posting a counter event from a UCommonActivatableWidget. In this case, we’re recording that a player selected a hero from the loadout screen:

void UMainMenu::HandleSendCounterEventClicked()
{
    if (ULocalPlayer* OwningLocalPlayer = GetOwningLocalPlayer();
        OwningLocalPlayer != nullptr)
    {
        if (UFirstLookSubsystem* FirstLookSubsystem =
            OwningLocalPlayer->GetSubsystem<UFirstLookSubsystem>())
        {
            FirstLookSubsystem->PostCounterEvent("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.

Parameters

Use PostCounterEventWithParam to split one event into variants, such as the level a player started or the item they bought, without defining a new event name for each. The same function is available in Blueprints as the Post Counter Event With Param node.

void UGameplayHud::HandleLevelStarted(const FString& LevelId)
{
    if (ULocalPlayer* OwningLocalPlayer = GetOwningLocalPlayer();
        OwningLocalPlayer != nullptr)
    {
        if (UFirstLookSubsystem* FirstLookSubsystem =
            OwningLocalPlayer->GetSubsystem<UFirstLookSubsystem>())
        {
            FirstLookSubsystem->PostCounterEventWithParam("level.started", LevelId, 1);
        }
    }
}

FirstLook stores the variant as level.started#forest_3, charts it under the base event on the Analytics page, and sums every variant into the base total. Parameters are trimmed and lowercased, may be at most 64 characters, and must not contain #. An empty parameter sends a plain event, and PostCounterEvent keeps working unchanged. Keep the set of values small, because each distinct parameter is tracked as its own variant.

Custom Duration Events

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.

The SDK exposes a StartDurationEvent / EndDurationEvent pair on the UFirstLookSubsystem:

UCLASS()
class FIRSTLOOKSDK_API UFirstLookSubsystem : public ULocalPlayerSubsystem
{
public:
    // ...
    UFUNCTION(BlueprintCallable, Category = FirstLook)
    void StartDurationEvent(FString DurationName);

    UFUNCTION(BlueprintCallable, Category = FirstLook)
    void EndDurationEvent(FString DurationName);
    // ...
}

Call StartDurationEvent when the activity begins and EndDurationEvent when it finishes. The SDK handles timing and delivery — you just provide a name.

Example

Below is an example that tracks how long a player spends in a match. StartDurationEvent is called when the match begins, and EndDurationEvent when it ends:

void AMyGameMode::OnMatchStart()
{
    for (APlayerController* PC : GetWorld()->GetPlayerControllerIterator())
    {
        if (ULocalPlayer* LP = PC->GetLocalPlayer())
        {
            if (UFirstLookSubsystem* FirstLook = LP->GetSubsystem<UFirstLookSubsystem>())
            {
                FirstLook->StartDurationEvent("match.round");
            }
        }
    }
}

void AMyGameMode::OnMatchEnd()
{
    for (APlayerController* PC : GetWorld()->GetPlayerControllerIterator())
    {
        if (ULocalPlayer* LP = PC->GetLocalPlayer())
        {
            if (UFirstLookSubsystem* FirstLook = LP->GetSubsystem<UFirstLookSubsystem>())
            {
                FirstLook->EndDurationEvent("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 EndDurationEvent 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.

Build Versions

Sessions, counter events, and duration events each record a build_version. FirstLook stores it as opaque text, so the format is entirely your studio’s choice: a semver, a CI build number, a branch-plus-commit string. Pick one convention and keep it stable, since the build filters on player filters match exact values.

By default the SDK reads your project version, so there is nothing to wire up: UFirstLookSubsystem reads ProjectVersion from [/Script/EngineSettings.GeneralProjectSettings] at startup, which is the value you set in Project Settings > Project > Description > Version.

To supply your own value instead, call OverrideBuildVersion (available in Blueprint and C++):

FirstLook->OverrideBuildVersion(TEXT("1.4.2"));

Set the version early

The session records the version sent on its session_start event, which goes out as soon as authentication succeeds, just before OnFirstLookReady fires. Call OverrideBuildVersion as soon as you have the subsystem. A later override applies only to events sent after it.

Players

Current Player

Call GetCurrentPlayer and bind OnCurrentPlayerAvailable to read the authenticated player’s FirstLook record, for example to decide whether to show a claim prompt.

C++

void UMainMenu::RefreshPlayer()
{
    UFirstLookSubsystem* FirstLook = GetOwningLocalPlayer()->GetSubsystem<UFirstLookSubsystem>();
    FirstLook->OnCurrentPlayerAvailable.AddUniqueDynamic(this, &UMainMenu::HandleCurrentPlayer);
    FirstLook->GetCurrentPlayer();
}

// Declared as a UFUNCTION, as AddDynamic requires.
void UMainMenu::HandleCurrentPlayer(const FFirstLookCurrentPlayerResponse& CurrentPlayer)
{
    if (CurrentPlayer.player.IsUnlinked())
    {
        GetOwningLocalPlayer()->GetSubsystem<UFirstLookSubsystem>()->GetPlayerClaim();
    }
}

Blueprint

Bind On Current Player Available, then call Get Current Player. Break the result and compare Player > State to unlinked; the IsUnlinked() and IsLinked() helpers are C++ only.

FFirstLookCurrentPlayerResponse carries player (id, state), steam (steam_id, empty when no Steam account is linked), discord (discord_id), and role (id, name). state is the player’s state as a lowercase string.

OnCurrentPlayerAvailable fires only on success. Failures are logged as GetCurrentPlayer failed: ....

Onboard Unlinked Players

The SDK creates new players in the Unlinked state. You can give these players a link that lets them claim their account and onboard to complete their profile, unlocking emails, rewards, Discord, friend invites, and everything else their role provides.

From Game Flow

To onboard unlinked players, first configure the From Game flow in the dashboard.

1. Enable the Unlinked Claiming toggle on the SDK configuration page.
2. Configure the Claim, Onboarding, and Complete steps of the From Game flow.
3. Optional - configure the role.

Provide Claim Link

After the From Game flow is set up, your game client can call the SDK method UFirstLookSubsystem::GetPlayerClaim and bind to the OnPlayerClaimAndCodeAvailable delegate. When the delegate is triggered, it provides a URL and a Base64-encoded QR code. Present this link or QR code to the player to allow them to complete email verification and any onboarding steps configured in the From Game flow.

Linking External Identities

After authentication has finished, call LinkIdentity with the provider name and the player’s ID on that service so FirstLook can match the two records. PlayFab is currently the only supported provider:

FirstLook->LinkIdentity(TEXT("playfab"), PlayFabId);

LinkIdentity reports its result only in the log. A failed link logs Failed to link identity playfab (response code ...) with the reason: 403 if linking is not enabled for your game (contact FirstLook), 409 if the ID belongs to another player, and 422 if it is empty or longer than 64 characters. Relinking the player’s own ID succeeds, so it is safe to call on every startup.

Entitlements

Entitlements are in-game items you grant to players from FirstLook. The SDK delivers entitlements of the FirstLook type: create one under Entitlements in the dashboard, then grant it to players, for example with the Grant Entitlement bulk action. Your game fetches a player’s outstanding entitlements, grants the items, and redeems each one so it is not delivered again. Pragma entitlements are delivered through Pragma instead and don’t appear here. If Entitlements doesn’t appear in your dashboard, contact FirstLook to enable it.

Not an ownership check

The list holds only entitlements that are unredeemed and not revoked. A redeemed entitlement disappears from it, so the list cannot answer “does this player own X?“. Track ownership in your own inventory.

Call	Success	Failure
GetEntitlements()	OnEntitlementsAvailable(Entitlements), an empty array when there are none	OnEntitlementsRequestFailed(StatusCode, Error)
RedeemEntitlement(EntitlementId)	OnEntitlementRedeemed(EntitlementId, RedeemedAt)	OnEntitlementRedeemFailed(EntitlementId, StatusCode, Error)

C++

void UInventoryWidget::NativeConstruct()
{
    Super::NativeConstruct();

    if (UFirstLookSubsystem* FirstLook = GetOwningLocalPlayer()->GetSubsystem<UFirstLookSubsystem>())
    {
        FirstLook->OnEntitlementsAvailable.AddDynamic(this, &UInventoryWidget::HandleEntitlements);
        FirstLook->GetEntitlements();
    }
}

void UInventoryWidget::HandleEntitlements(const TArray<FFirstLookEntitlement>& Entitlements)
{
    UFirstLookSubsystem* FirstLook = GetOwningLocalPlayer()->GetSubsystem<UFirstLookSubsystem>();
    for (const FFirstLookEntitlement& Entitlement : Entitlements)
    {
        // Key the grant on Entitlement.id so a retried redeem grants the item once.
        GrantItemOnce(Entitlement.id, Entitlement.sku);
        FirstLook->RedeemEntitlement(Entitlement.id);
    }
}

Blueprint

Bind On Entitlements Available, then call Get Entitlements. Loop over the array, grant each item once by its Sku, and call Redeem Entitlement with its Id. Bind On Entitlement Redeem Failed to catch failures.

Each FFirstLookEntitlement carries id, entitlement_type, name, sku, redeemable_type_id, and created_at. Match items on sku, the Entitlement ID you set in the dashboard, and never on name, which is a display string that can be translated or renamed.

Redeeming is one-shot. Redeeming the same entitlement again fails with 400 and Entitlement already redeemed, which usually means an earlier attempt succeeded, so treat it as done.

Watermark Overlay

The SDK can watermark your playtest builds. Each session gets a unique code, and the SDK tiles it across the screen at an angle, drifting slowly, with the center always covered so cropping can’t remove it. If a screenshot or stream leaks, the code traces it back to the player and session it came from.

Availability

Watermarking must be enabled for your game by FirstLook. If the Playtest Watermark section doesn’t appear on your SDK configuration page, contact FirstLook.

1. On the SDK configuration page, turn on Enable Watermark under Playtest Watermark, then click Save Changes.
2. After the session starts, the SDK fetches the session’s code and draws the overlay on the first local player’s viewport automatically.
3. To trace a leak, enter the code on the Search watermark page to find the player and session it belongs to.

FirstLook controls only whether the watermark is on. How it looks is set in your project, under Edit > Project Settings > Plugins > FirstLook in the Watermark section, or in DefaultGame.ini:

[/Script/FirstLookSDK.FirstLookSDKSettings]
WatermarkOpacity=0.18
WatermarkTileDensity=5.0
WatermarkAngleDegrees=30.0
WatermarkDriftSpeed=0.5
bWatermarkIncludeCenter=True

Setting	Default	Range	Effect
WatermarkColor	White		Text color
WatermarkOpacity	0.18	0 to 1	Text opacity
WatermarkTileDensity	5.0	1 to 12	Roughly how many codes fit across the screen width
WatermarkAngleDegrees	30.0	0 to 90	Tilt of the grid
WatermarkDriftSpeed	0.5	0 to 2	0 holds the grid still
bWatermarkIncludeCenter	true		Keeps the screen center covered

OnWatermarkEnabled fires once per session when the overlay appears, carrying the code. The overlay renders itself, so bind it only if you want to tell players their session is watermarked. It is available in Blueprint as On Watermark Enabled.

If watermarking is not enabled for your game, the SDK logs Watermark: watermarking is not enabled for this game. Contact FirstLook to enable it. and the game runs without an overlay. Transient fetch failures are retried, and a fetch that keeps failing leaves the game running without one.

Tuning without a server

In non-shipping builds, firstlook.watermark.show <CODE> draws the overlay with any code so you can adjust the settings live, firstlook.watermark.hide removes it, and firstlook.watermark.status prints the current state and settings.