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 プロジェクトがあることを前提とします。
管理ダッシュボードから FirstLook Unity SDK を入手してください。

- FirstLook で Steam ゲームをセットアップしてください。Steam インテグレーションを参照してください。
テストプレイヤーを Steam アカウントにリンクした状態でプレイテストに招待してください。プレイヤーの招待を参照してください。
セットアップに必要な値を収集してください。
- FirstLook ゲーム設定の
gameSlug - FirstLook ドメイン設定の
clientUrl - Steam App ID
クライアント URL を確認するには、FirstLook 設定からドメインを確認してください。

- FirstLook ゲーム設定の
管理ダッシュボードから FirstLook Unity SDK を入手してください。

FirstLook で Google Play をセットアップしてください。クローズドテストトラックの設定、必要な OAuth 2.0 認証情報の作成、クライアント ID の FirstLook への追加方法については、Google Play インテグレーションガイドを参照してください。
具体的には、FirstLook ダッシュボードの Config > Google Play に Web application OAuth 2.0 クライアント ID(Android クライアント ID ではない)を追加する必要があります。また、Google がビルドからのサインインリクエストを受け付けるよう、アプリのパッケージ名と SHA-1 フィンガープリントで登録された Android OAuth クライアントも必要です。
セットアップに必要な値を収集してください。
- FirstLook ゲーム設定の
gameSlug - FirstLook ドメイン設定の
clientUrl
- FirstLook ゲーム設定の
FirstLook Unity パッケージのインストール
Section titled “FirstLook Unity パッケージのインストール”FirstLook Unity SDK を入手し、FirstLook でゲームをセットアップしたら、Unity プロジェクトにパッケージをインストールします。
FirstLookUnitySdk.zip(管理ダッシュボードからダウンロードしたファイル)を解凍して、com.pragma.firstlook.coreとcom.pragma.firstlook.uiパッケージのターボールを展開してください。- Unity Editor で
Window > Package Managerを開いてください。 + > Add package from tarball...を選択して、zip から展開したcom.pragma.firstlook.coreターボールをインストールしてください。これは必須パッケージです。パッケージ化されたネイティブゲーム内アンケート UI が必要な場合は、
com.pragma.firstlook.uiに対して同じAdd package from tarball...手順を繰り返してください。アンケート UI を自分でレンダリングする予定がある場合は、このパッケージをスキップできます。プラットフォーム認証の依存関係を追加してください。
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が有効になります。FirstLook SDK は生の Google ID トークンを受け付けるため、それを提供できる任意の Google サインインライブラリを使用できます。たとえば、Google Play Games Plugin for Unity や Google Sign-In Unity Plugin などがあります。
お好みの Google サインインライブラリをインストールし、FirstLook ダッシュボードに追加した Web application クライアント ID で設定してください。これはサインインの開始と結果の ID トークンの検証の両方に使用されるため、同じクライアント ID である必要があります。
ユーザーがサインインしたら、ライブラリから ID トークンを取得して
AuthenticateWithGoogle(idToken)に渡してください。正確な API はライブラリによって異なります。- Google Play Games Plugin:
PlayGamesClientConfigurationでRequestIdToken = trueを設定し、サインイン後に((PlayGamesLocalUser)Social.localUser).GetIdToken()でトークンを取得します。 - Google Sign-In Unity Plugin:
GoogleSignIn.DefaultInstance.SignIn()が解決した後、結果からGoogleSignInUser.IdTokenを読み取ります。
完全なサインインセットアップについては、選択したライブラリのドキュメントを参照してください。
- Google Play Games Plugin:
FirstLookSettings の設定
Section titled “FirstLookSettings の設定”Unity SDK は FirstLookSettings アセットから設定を読み込みます。
Unity Editor で
Assets/Resources/FirstLookSettings.assetを作成してください。Assets > Create > FirstLook > Settings
アセットの必須フィールドを設定してください。
apiUrl:https://api.firstlook.ggclientUrl:https://<game-slug>.firstlook.gggameSlug: FirstLook のゲームスラッグbuildVersion: アナリティクスイベントに付加されるオプションのビルドラベル(ビルドバージョンを参照)
プロジェクトで異なる動作が必要でない限り、リトライ、キュー、ログ設定はデフォルトのままにしてください。
FirstLookSurveyPresenter と FirstLookAutoLifecycle は、設定が割り当てられていない場合、FirstLookSettings.LoadFromResources() で設定を読み込みます。これは Resources/FirstLookSettings を読み込み、Editor および開発ビルドでは Resources/FirstLookSettingsLocal が存在する場合にそちらを優先します。ローカルアセットを使用して、出荷するアセットを変更せずにローカルビルドをテストゲームに向けることができます。
clientUrl は ActivateSurveyBrowserOverlay(...) を通じてブラウザー配信アンケートを開く予定がある場合にのみ必要です。
認証ブートストラップ
Section titled “認証ブートストラップ”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 }}Google サインインライブラリを使用して Google ID トークンを取得し、FirstLook に渡してください。
using Pragma.FirstLook;using UnityEngine;
public sealed class FirstLookStartup : MonoBehaviour{ [SerializeField] private FirstLookSettings firstLookSettings;
private FirstLookClient _client;
// Google サインインライブラリ(例: Google Play Games Plugin または // Google Sign-In Unity Plugin)から Google ID トークンを取得したら、 // このメソッドを一度呼び出してください。 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}"); }}ログインのテスト
Section titled “ログインのテスト”Unity SDK がインストールされ設定が完了したら、ローカルで Steam 統合をテストしてください。
FirstLook スタートアップコードが実行される前に Steamworks を初期化してください。
たとえば、
FirstLookSteamHelper.GetSessionTicket()を呼び出す前にAwake()でSteamAPI.Init()を呼び出すシーンオブジェクトを追加してください。
- Unity Editor で Play を押すか、開発ビルドを実行してください。
Unity コンソールで、ブートストラップコードからの起動成功ログを確認してください。
- 例:
[FirstLookStartup] FirstLook ready. Session: 8c3b8f66-...
- 例:
Steam のセットアップが不完全な場合は、代わりに以下のいずれかの失敗シグナルが表示されます。
[SteamManager] SteamAPI.Init() failed...[FirstLookStartup] Steam ticket unavailable...[FirstLookStartup] FirstLook startup failed: ...
Google Play サービスが利用可能なデバイスまたはエミュレーターで Google Play 統合をテストしてください。
Google サインインライブラリを初期化し、サインインフローを実行して Google ID トークンを取得してください。
ブートストラップコードの
AuthenticateWithGoogle(idToken)にトークンを渡してください。Unity コンソールで起動成功ログを確認してください。
- 例:
[FirstLookStartup] FirstLook ready. Session: 8c3b8f66-...
- 例:
認証に失敗した場合は、以下のいずれかのシグナルが表示されます。
[FirstLookStartup] Google ID token was empty.[FirstLookStartup] FirstLook startup failed: Invalid Google ID token: ...
ゲーム内アンケートのテスト
Section titled “ゲーム内アンケートのテスト”ログインとセッション開始が正常に動作したら、Unity からゲーム内アンケートをトリガーできます。
ゲームクライアント配信を有効にしたアンケートを作成してください。アンケートの作成を参照してください。
新しく作成したアンケートのトリガーをセットアップしてください。トリガーのセットアップを参照してください。
パッケージ化されたネイティブアンケート UI が必要な場合は、
com.pragma.firstlook.uiをインストールし、シーンにFirstLookSurveyPresenterとFirstLookSurveyCanvasを追加してください。FirstLookSurveyPresenterはOnNewNativeSurveyAvailableをサブスクライブし、アクティブなアンケートをキャッシュして、TryShowCurrentSurvey()で再表示できます。UI パッケージに付属のパッケージ化されたアンケートプレハブ、スキン、テーマアセットを出発点として、カスタマイズしたい場合はプロジェクトに複製してください。
ブラウザー配信アンケートが必要な場合は、ホストコードで
OnNewBrowserSurveyAvailableをサブスクライブし、ActivateSurveyBrowserOverlay(surveyUuid)を呼び出してください。- 付属の Unity UI パッケージはブラウザー配信アンケートを自動的に開きません。
ゲームからアンケートをトリガーしてください。
await _client.PostSurveyTriggerEventAsync("match.completed");
完全にカスタムのアンケート UI を構築している場合は、com.pragma.firstlook.ui をまったく使用せず、FirstLookClient のコアアンケートイベントを直接サブスクライブできます。
セッションとイベント
Section titled “セッションとイベント”セッション追跡
Section titled “セッション追跡”Unity SDK はインストールされただけではセッションを開始しません。セッションはホストが StartSessionAsync() を呼び出すか、AuthenticateAndStartSessionAsync(...) が正常に完了したときに開始されます。
開始後、SDK はセッションを終了するかアプリがシャットダウンするまでアクティブセッションを追跡します。内部的には、FirstLookRuntimeDriver がアプリケーション終了時にベストエフォートのグレースフルシャットダウンとして EndSessionAsync() を呼び出します。FirstLook アカウントをまだ作成していないプレイヤーも追跡されます。彼らはダッシュボードで未リンクプレイヤーとして表示され、プラットフォームアカウントが関連付けられます。
セッションが記録されると、アナリティクスページの「リテンション」タブと各プレイヤープロフィールでプレイヤーのアクティビティとセッション時間データを確認できます。
カスタムイベント
Section titled “カスタムイベント”セッション追跡に加えて、独自のゲームプレイイベントを計測して、ヒーロー選択、マッチ結果、ストア購入など、スタジオにとって最も重要なことを捉えることができます。FirstLookClient の PostCounterEventAsync(...) を使用して、整数値を持つ名前付きカウンターを送信してください。
public async void HandleHeroSelected(){ if (_client == null || !_client.IsSessionActive) return;
await _client.PostCounterEventAsync("loadout.hero-a-selected", 1);}イベントの命名とグループ化
Section titled “イベントの命名とグループ化”イベント名は <カテゴリ>.<イベントタイプ> の規則に従います。このパターンを使用すると、FirstLook はアナリティクスページとプレイヤープロフィールで関連するイベントを自動的にグループ化し、カテゴリ別にメトリクスを参照しやすくします。
ゲーム内でイベントが発生する場所を反映したカテゴリ名前空間を選択してください。たとえば、match、lobby、menu、store、in-game などです。必要なだけカテゴリを自由に定義できます。
パラメーター
Section titled “パラメーター”オプションのパラメーターを渡すことで、プレイヤーが開始したレベルや購入したアイテムなど、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 引数のオーバーロードは引き続き変更なく動作します。各固有パラメーターは独自のバリアントとして追跡されるため、値のセットは小さく保ってください。
カスタム継続時間イベント
Section titled “カスタム継続時間イベント”カウンターイベントは何かが起こったことを記録しますが、どれだけの時間 がかかったかを知る必要がある場合もあります。継続時間イベントを使用すると、マッチ、ローディング画面、メニューでの滞在時間など、ゲーム内の 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");}イベントの命名とグループ化
Section titled “イベントの命名とグループ化”継続時間イベント名はカウンターイベントと同じ <カテゴリ>.<イベントタイプ> の規則に従います。FirstLook はアナリティクスページでカテゴリプレフィックスによって自動的にグループ化します。
ビルドバージョン
Section titled “ビルドバージョン”セッション、カウンター、継続時間の各イベントはそれぞれ 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 フィールドにフォールバックします。
現在のプレイヤー
Section titled “現在のプレイヤー”GetCurrentPlayerAsync() を呼び出して認証済みプレイヤーの FirstLook レコードを読み取ります。たとえば、クレームプロンプトを表示するかどうかを判断するために使用できます。
public async void RefreshPlayer(){ var me = await _client.GetCurrentPlayerAsync(); if (me == null) return;
if (me.Player.IsUnlinked) await _client.GetPlayerClaimAsync();}クライアントが認証されていないか、リクエストが失敗した場合、呼び出しは null を返します。
| フィールド | 内容 |
|---|---|
Player.Id | FirstLook プレイヤー 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 フロー
Section titled “From Game フロー”未リンクプレイヤーをオンボーディングするには、まずダッシュボードで From Game フローを設定してください。
- SDK 設定ページの Unlinked Claiming トグルを有効にしてください。
- From Game フローの Claim、Onboarding、Complete ステップを設定してください。
- 任意 - ロールを設定してください。
クレームリンクの提供
Section titled “クレームリンクの提供”From Game フローがセットアップされると、ゲームクライアントは FirstLookClient の GetPlayerClaimAsync() を呼び出し、OnPlayerClaimAvailable イベントをサブスクライブできます。イベントがトリガーされると、URL と Base64 エンコードされた QR コードが提供されます。このリンクまたは QR コードをプレイヤーに提示して、メール認証と From Game フローで設定されたオンボーディングステップを完了させてください。
外部 ID のリンク
Section titled “外部 ID のリンク”プレイヤーが認証されたら、外部サービスでのプレイヤーの 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 はすでにこのゲームの別のプレイヤーにリンクされています。 |
422 | ID が空か 64 文字を超えています。 |
失敗はリトライのためにキューに入れられるのではなく、返されます。
エンタイトルメント
Section titled “エンタイトルメント”エンタイトルメントは 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 はそれを画面全体にゆっくりとドリフトしながら斜めにタイル表示します。中央は常にカバーされるため、クロッピングで除去することはできません。スクリーンショットやストリームが漏洩した場合、コードによってどのプレイヤーのセッションから来たものかを特定できます。
- SDK 設定ページの Playtest Watermark で Enable Watermark をオンにし、Save Changes をクリックしてください。
- セッションが開始されると、SDK がそのセッションのコードを取得し、オーバーレイを自動的に描画します。セッションが終了するとオーバーレイは削除され、次のセッションには独自のコードが表示されます。
- 漏洩を追跡するには、ウォーターマーク検索ページにコードを入力して、それが属するプレイヤーとセッションを見つけてください。
FirstLook はウォーターマークのオン・オフのみを制御します。見た目はプロジェクトで設定します。オーバーレイはすべての UI の上に表示されるスクリーンスペースキャンバスで、シーンのロードをまたいで持続し、入力をブロックしません。FirstLookSettings アセットの Watermark セクションで調整してください。
| フィールド | デフォルト | 範囲 | 効果 |
|---|---|---|---|
color | White | テキストの色 | |
opacity | 0.06 | 0 〜 1 | テキストの不透明度 |
tileDensity | 5 | 1 〜 12 | 画面幅に収まるおおよそのコード数 |
angleDegrees | 30 | 0 〜 90 | グリッドの傾き |
driftSpeed | 0.5 | 0 〜 2 | 0 でグリッドを静止させる |
includeCenter | true | 画面中央をカバーし続ける |
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 以下に設定してください。