コンテンツにスキップ
Get Started

Unity SDK セットアップ

FirstLook Unity SDK を使用すると、Unity ゲームから FirstLook と連携できます。SDK は Steam および Google Play 認証、ゲーム内アンケート、セッション追跡、カスタムイベント、カスタム継続時間イベント、プレイヤールックアップ、PlayFab ID リンク、エンタイトルメント、プレイテストウォーターマークをサポートしています。

SDK は 2 つの Unity パッケージとして提供されます。

  • com.pragma.firstlook.core は認証、セッション、アナリティクス、アンケート転送に必要なランタイムパッケージです。
  • com.pragma.firstlook.ui は core 上に構築されたオプションのネイティブアンケート UI パッケージです。

主な統合インターフェースは FirstLookClient で、FirstLookBootstrap.InitializeWithSettings(...) を通じて初期化します。UI パッケージをインストールした場合、FirstLookSurveyPresenter がネイティブゲーム内アンケートレンダリングのメインエントリーポイントになります。

このセットアップガイドでは、MyGame という名前の Unity プロジェクトがあることを前提とします。

  1. 管理ダッシュボードから FirstLook Unity SDK を入手してください。Download
SDK

  2. FirstLook で Steam ゲームをセットアップしてください。Steam インテグレーションを参照してください。
  3. テストプレイヤーを Steam アカウントにリンクした状態でプレイテストに招待してください。プレイヤーの招待を参照してください。

  4. セットアップに必要な値を収集してください。

    • FirstLook ゲーム設定の gameSlug
    • FirstLook ドメイン設定の clientUrl
    • Steam App ID

    クライアント URL を確認するには、FirstLook 設定からドメインを確認してください。 Client URL

FirstLook Unity パッケージのインストール

Section titled “FirstLook Unity パッケージのインストール”

FirstLook Unity SDK を入手し、FirstLook でゲームをセットアップしたら、Unity プロジェクトにパッケージをインストールします。

  1. FirstLookUnitySdk.zip(管理ダッシュボードからダウンロードしたファイル)を解凍して、com.pragma.firstlook.core と com.pragma.firstlook.ui パッケージのターボールを展開してください。

  2. Unity Editor で Window > Package Manager を開いてください。
  3. + > Add package from tarball... を選択して、zip から展開した com.pragma.firstlook.core ターボールをインストールしてください。これは必須パッケージです。

  4. パッケージ化されたネイティブゲーム内アンケート UI が必要な場合は、com.pragma.firstlook.ui に対して同じ Add package from tarball... 手順を繰り返してください。アンケート UI を自分でレンダリングする予定がある場合は、このパッケージをスキップできます。

  5. プラットフォーム認証の依存関係を追加してください。

    Packages/manifest.json に Steamworks.NET を追加してください。

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

    Steamworks.NET がインストールされると、Unity は自動的に FIRSTLOOK_STEAMWORKS を定義し、FirstLookSteamHelper が有効になります。

Unity SDK は FirstLookSettings アセットから設定を読み込みます。

  1. Unity Editor で Assets/Resources/FirstLookSettings.asset を作成してください。

    • Assets > Create > FirstLook > Settings
  2. アセットの必須フィールドを設定してください。

    • apiUrl: https://api.firstlook.gg
    • clientUrl: https://<game-slug>.firstlook.gg
    • gameSlug: FirstLook のゲームスラッグ
    • buildVersion: アナリティクスイベントに付加されるオプションのビルドラベル(ビルドバージョンを参照)
  3. プロジェクトで異なる動作が必要でない限り、リトライ、キュー、ログ設定はデフォルトのままにしてください。

FirstLookSurveyPresenter と FirstLookAutoLifecycle は、設定が割り当てられていない場合、FirstLookSettings.LoadFromResources() で設定を読み込みます。これは Resources/FirstLookSettings を読み込み、Editor および開発ビルドでは Resources/FirstLookSettingsLocal が存在する場合にそちらを優先します。ローカルアセットを使用して、出荷するアセットを変更せずにローカルビルドをテストゲームに向けることができます。

clientUrl は ActivateSurveyBrowserOverlay(...) を通じてブラウザー配信アンケートを開く予定がある場合にのみ必要です。

Unity の推奨統合方法はホスト所有のブートストラップです。FirstLook を一度初期化し、プラットフォームで認証して、セッションを明示的に開始します。

Steamworks がすでに初期化されていることを確認してから、認証してセッションを開始してください。

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
}
}

Unity SDK がインストールされ設定が完了したら、ローカルで Steam 統合をテストしてください。

  1. FirstLook スタートアップコードが実行される前に Steamworks を初期化してください。

    • たとえば、FirstLookSteamHelper.GetSessionTicket() を呼び出す前に Awake() で SteamAPI.Init() を呼び出すシーンオブジェクトを追加してください。

  2. Unity Editor で Play を押すか、開発ビルドを実行してください。
  3. Unity コンソールで、ブートストラップコードからの起動成功ログを確認してください。

    • 例: [FirstLookStartup] FirstLook ready. Session: 8c3b8f66-...
  4. Steam のセットアップが不完全な場合は、代わりに以下のいずれかの失敗シグナルが表示されます。

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

ログインとセッション開始が正常に動作したら、Unity からゲーム内アンケートをトリガーできます。

  1. ゲームクライアント配信を有効にしたアンケートを作成してください。アンケートの作成を参照してください。

  2. 新しく作成したアンケートのトリガーをセットアップしてください。トリガーのセットアップを参照してください。

  3. パッケージ化されたネイティブアンケート UI が必要な場合は、com.pragma.firstlook.ui をインストールし、シーンに FirstLookSurveyPresenter と FirstLookSurveyCanvas を追加してください。

    • FirstLookSurveyPresenter は OnNewNativeSurveyAvailable をサブスクライブし、アクティブなアンケートをキャッシュして、TryShowCurrentSurvey() で再表示できます。

    • UI パッケージに付属のパッケージ化されたアンケートプレハブ、スキン、テーマアセットを出発点として、カスタマイズしたい場合はプロジェクトに複製してください。

  4. ブラウザー配信アンケートが必要な場合は、ホストコードで OnNewBrowserSurveyAvailable をサブスクライブし、ActivateSurveyBrowserOverlay(surveyUuid) を呼び出してください。

    • 付属の Unity UI パッケージはブラウザー配信アンケートを自動的に開きません。
  5. ゲームからアンケートをトリガーしてください。

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

完全にカスタムのアンケート UI を構築している場合は、com.pragma.firstlook.ui をまったく使用せず、FirstLookClient のコアアンケートイベントを直接サブスクライブできます。

Unity SDK はインストールされただけではセッションを開始しません。セッションはホストが StartSessionAsync() を呼び出すか、AuthenticateAndStartSessionAsync(...) が正常に完了したときに開始されます。

開始後、SDK はセッションを終了するかアプリがシャットダウンするまでアクティブセッションを追跡します。内部的には、FirstLookRuntimeDriver がアプリケーション終了時にベストエフォートのグレースフルシャットダウンとして EndSessionAsync() を呼び出します。FirstLook アカウントをまだ作成していないプレイヤーも追跡されます。彼らはダッシュボードで未リンクプレイヤーとして表示され、プラットフォームアカウントが関連付けられます。

セッションが記録されると、アナリティクスページの「リテンション」タブと各プレイヤープロフィールでプレイヤーのアクティビティとセッション時間データを確認できます。

セッション追跡に加えて、独自のゲームプレイイベントを計測して、ヒーロー選択、マッチ結果、ストア購入など、スタジオにとって最も重要なことを捉えることができます。FirstLookClient の PostCounterEventAsync(...) を使用して、整数値を持つ名前付きカウンターを送信してください。

public async void HandleHeroSelected()
{
if (_client == null || !_client.IsSessionActive)
return;
await _client.PostCounterEventAsync("loadout.hero-a-selected", 1);
}

イベント名は <カテゴリ>.<イベントタイプ> の規則に従います。このパターンを使用すると、FirstLook はアナリティクスページとプレイヤープロフィールで関連するイベントを自動的にグループ化し、カテゴリ別にメトリクスを参照しやすくします。

ゲーム内でイベントが発生する場所を反映したカテゴリ名前空間を選択してください。たとえば、match、lobby、menu、store、in-game などです。必要なだけカテゴリを自由に定義できます。

オプションのパラメーターを渡すことで、プレイヤーが開始したレベルや購入したアイテムなど、1 つのイベントをバリアントに分割できます。バリアントごとに新しいイベント名を定義する必要はありません。

public async void HandleLevelStarted(string levelId)
{
if (_client == null || !_client.IsSessionActive)
return;
await _client.PostCounterEventAsync("level.started", levelId, 1);
}

FirstLook はバリアントを level.started#forest_3 として保存し、アナリティクスページのベースイベントの下にチャートとして表示し、すべてのバリアントをベース合計に集計します。パラメーターはトリミングされ小文字に変換されます。最大 64 文字で、# を含んではなりません。空のパラメーターはプレーンイベントとして送信され、2 引数のオーバーロードは引き続き変更なく動作します。各固有パラメーターは独自のバリアントとして追跡されるため、値のセットは小さく保ってください。

カウンターイベントは何かが起こったことを記録しますが、どれだけの時間 がかかったかを知る必要がある場合もあります。継続時間イベントを使用すると、マッチ、ローディング画面、メニューでの滞在時間など、ゲーム内の 2 つの明示的なポイント間の経過時間を計測できます。

アクティビティが始まったときに StartDurationEventAsync(...) を呼び出し、終了したときに EndDurationEventAsync(...) を呼び出してください。SDK がタイミングと配信を処理するため、名前を指定するだけです。

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");
}

継続時間イベント名はカウンターイベントと同じ <カテゴリ>.<イベントタイプ> の規則に従います。FirstLook はアナリティクスページでカテゴリプレフィックスによって自動的にグループ化します。

セッション、カウンター、継続時間の各イベントはそれぞれ build_version を持つことができます。FirstLook はそれを不透明なラベルとして扱い、送信した内容をそのまま保存するため、フォーマットはスタジオが完全に選択できます。1.4.2 のようなセマバー、CI ビルド番号、ブランチとコミットを組み合わせた文字列など。プレイヤーフィルターのビルドフィルターは完全一致でマッチするため、1 つの規則を選び安定させてください。

提供方法は優先度順に 3 つあります。

ソース方法最適な用途
ランタイムオーバーライドclient.OverrideBuildVersion("1.4.2")起動時に独自のビルドパイプラインからバージョンを読み取る場合
自動FirstLookSettings の buildVersionSource配線不要: ApplicationVersion は Player Settings を読み取り、SteamAppId は実行中の Steam App ID を読み取り、Steam プレイテストアプリをメインアプリから区別する
設定フィールドFirstLookSettings の buildVersionビルドごとに手動で設定するラベル

buildVersionSource のデフォルトは Manual で、buildVersion フィールドをそのまま使用します。解決できないソース(例: Steamworks.NET がインストールされていない場合の SteamAppId)は buildVersion フィールドにフォールバックします。

GetCurrentPlayerAsync() を呼び出して認証済みプレイヤーの FirstLook レコードを読み取ります。たとえば、クレームプロンプトを表示するかどうかを判断するために使用できます。

public async void RefreshPlayer()
{
var me = await _client.GetCurrentPlayerAsync();
if (me == null)
return;
if (me.Player.IsUnlinked)
await _client.GetPlayerClaimAsync();
}

クライアントが認証されていないか、リクエストが失敗した場合、呼び出しは null を返します。

フィールド内容
Player.IdFirstLook プレイヤー ID
Player.Stateプレイヤーの状態(unlinked や onboarded などの小文字文字列)
Steam.SteamIdリンクされた Steam ID。Steam アカウントがリンクされていない場合、Steam は null
Discord.DiscordIdリンクされた Discord ID。Discord アカウントがリンクされていない場合、Discord は null
Role.Id, Role.Nameプレイヤーのロール

FirstLook は時間の経過とともに状態を追加する可能性があるため、State 文字列を比較するのではなく、Player.IsUnlinked と Player.IsLinked を確認してください。

未リンクプレイヤーのオンボーディング

Section titled “未リンクプレイヤーのオンボーディング”

SDK は新しいプレイヤーを未リンク状態で作成します。これらのプレイヤーに、アカウントをクレームしてプロフィールを完成させるためのリンクを提供することができます。これにより、メール、報酬、Discord、フレンド招待など、ロールが提供するすべての機能が利用可能になります。

未リンクプレイヤーをオンボーディングするには、まずダッシュボードで From Game フローを設定してください。

  1. SDK 設定ページの Unlinked Claiming トグルを有効にしてください。
  2. From Game フローの Claim、Onboarding、Complete ステップを設定してください。
  3. 任意 - ロールを設定してください。

From Game フローがセットアップされると、ゲームクライアントは FirstLookClient の GetPlayerClaimAsync() を呼び出し、OnPlayerClaimAvailable イベントをサブスクライブできます。イベントがトリガーされると、URL と Base64 エンコードされた QR コードが提供されます。このリンクまたは QR コードをプレイヤーに提示して、メール認証と From Game フローで設定されたオンボーディングステップを完了させてください。

プレイヤーが認証されたら、外部サービスでのプレイヤーの ID を FirstLook に伝えることで、2 つのレコードをマッチさせることができます。現在サポートされているプロバイダーは PlayFab のみです。

var result = await _client.LinkIdentityAsync(FirstLookIdentityProvider.Playfab, playfabId);
if (!result.Success)
{
Debug.LogWarning($"PlayFab link failed (status={result.StatusCode}): {result.Error}");
}

プレイヤー自身の ID を再リンクしても成功するため、起動のたびに呼び出しても安全です。

ステータス意味
403このゲームでこのプロバイダーのリンクが有効になっておらず、result.Code が FeatureNotEnabled。有効にするには FirstLook に連絡してください。
409その ID はすでにこのゲームの別のプレイヤーにリンクされています。
422ID が空か 64 文字を超えています。

失敗はリトライのためにキューに入れられるのではなく、返されます。

エンタイトルメントは FirstLook からプレイヤーに付与するゲーム内アイテムです。SDK は FirstLook タイプのエンタイトルメントを配信します。ダッシュボードの Entitlements でエンタイトルメントを作成し、たとえば Grant Entitlement の一括アクションでプレイヤーに付与します。ゲームはプレイヤーの未処理のエンタイトルメントを取得し、アイテムを付与して、再度配信されないよう各エンタイトルメントを引き換えます。Pragma エンタイトルメントは Pragma を通じて配信されるため、ここには表示されません。ダッシュボードに Entitlements が表示されない場合は、FirstLook に連絡して有効にしてください。

public async void SyncEntitlements()
{
var result = await _client.GetEntitlementsAsync();
if (!result.Success)
{
Debug.LogWarning($"Entitlements unavailable (status={result.StatusCode}): {result.Error}");
return;
}
foreach (var entitlement in result.Entitlements)
{
// リトライ時の引き換えでアイテムが一度だけ付与されるよう、entitlement.Id をキーにする。
MyInventory.GrantOnce(entitlement.Id, entitlement.Sku);
var redeem = await _client.RedeemEntitlementAsync(entitlement.Id);
if (!redeem.Success && redeem.Error != "Entitlement already redeemed")
Debug.LogWarning($"Redeem {entitlement.Id} failed (status={redeem.StatusCode}): {redeem.Error}");
}
}

各 FirstLookEntitlement は Id、EntitlementType、Name、Sku、RedeemableTypeId、CreatedAt を持ちます。ダッシュボードで設定した Entitlement ID である Sku でアイテムを照合し、翻訳や名前変更が可能な表示文字列である Name では照合しないでください。

引き換えはワンショットです。同じエンタイトルメントを再度引き換えると 400 と Entitlement already redeemed で失敗します。これは通常、以前の試みが成功したことを意味するため、完了として扱ってください。どちらの呼び出しもリトライのためにキューに入れられません。失敗は Success、StatusCode、Error で返されます。

ウォーターマークオーバーレイ

Section titled “ウォーターマークオーバーレイ”

SDK はプレイテストビルドにウォーターマークを付けることができます。各セッションに固有のコードが割り当てられ、SDK はそれを画面全体にゆっくりとドリフトしながら斜めにタイル表示します。中央は常にカバーされるため、クロッピングで除去することはできません。スクリーンショットやストリームが漏洩した場合、コードによってどのプレイヤーのセッションから来たものかを特定できます。

  1. SDK 設定ページの Playtest Watermark で Enable Watermark をオンにし、Save Changes をクリックしてください。
  2. セッションが開始されると、SDK がそのセッションのコードを取得し、オーバーレイを自動的に描画します。セッションが終了するとオーバーレイは削除され、次のセッションには独自のコードが表示されます。
  3. 漏洩を追跡するには、ウォーターマーク検索ページにコードを入力して、それが属するプレイヤーとセッションを見つけてください。

FirstLook はウォーターマークのオン・オフのみを制御します。見た目はプロジェクトで設定します。オーバーレイはすべての UI の上に表示されるスクリーンスペースキャンバスで、シーンのロードをまたいで持続し、入力をブロックしません。FirstLookSettings アセットの Watermark セクションで調整してください。

フィールドデフォルト範囲効果
colorWhiteテキストの色
opacity0.060 〜 1テキストの不透明度
tileDensity51 〜 12画面幅に収まるおおよそのコード数
angleDegrees300 〜 90グリッドの傾き
driftSpeed0.50 〜 20 でグリッドを静止させる
includeCentertrue画面中央をカバーし続ける

OnWatermarkEnabled をサブスクライブするとオーバーレイが表示されるタイミングを把握できます。このイベントにはコードが含まれます。オーバーレイは自動的にレンダリングされるため、これはプレイテストセッションがウォーターマーク付きであることをプレイヤーに伝えるためだけに使用してください。

_client.OnWatermarkEnabled += code => ShowToast("This playtest session is watermarked.");

ウォーターマークがゲームで有効になっていない場合、ゲームはオーバーレイなしで実行され、SDK は次の警告をログに記録します: Watermarking is not enabled for this game. Contact FirstLook to enable it. これを確認するには、FirstLookSettings の logLevel を Warning 以下に設定してください。