カタログ v2 クイックスタート

[アーティクル]
07/27/2023

Important

エコノミー v2 が一般提供になりました。サポートとフィードバックについては、PlayFab フォーラムをご利用ください。

ゲームマネージャーに慣れた後は、次のことができます。

v2 カタログの権限、設定、項目をセットアップします。
受信検証を設定する
アイテムの購入手順を確認する

Unity の詳細なチュートリアルについては、Unity 固有のチュートリアルを参照してください。

パート 1: カタログの概要

ステップ 1 – 権限を取得する

最初のステップは、ゲームマネージャー UI の設定ページの ⚙️ タイトル設定>エコノミー (V2) でカタログを有効にすることです。 UpdateCatalogConfig API を使用して、IsCatalogEnabled フラグを true に設定できます。

カタログを操作するには、GameManger にログインしてサイトツールを使用するか、API を使用するためのエンティティトークンを取得する必要があります。エンティティトークンを取得する最も簡単な方法は、GetEntityToken API を使用することです。

注意

API を管理者または権限のあるサービスとして呼び出すには (最初のカタログアイテムを作成する前に行う必要があります)、タイトルの秘密キーを含む X-SecretKey ヘッダーを含める必要があります。タイトルの秘密キーは、ゲームマネージャー UI の ⚙️ [タイトル設定>秘密キー] で作成できます。

API
C# SDK

curl \
  -H "X-SecretKey: {{SecretKey}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{titleId}}.playfabapi.com/Authentication/GetEntityToken \
  -d "{\"CustomTags\": {\"user\": \"{{email}}\"}}"

// ENABLE_PLAYFABSERVER_API symbol denotes this is an admin-level game server and not a game client.
private static async Task PlayFabEconomyv2QuickStart()
{
#if ENABLE_PLAYFABSERVER_API
    string systemGUID = Environment.GetEnvironmentVariable("SYSTEM_GUID", EnvironmentVariableTarget.Process);
    PlayFabSettings.staticSettings.DeveloperSecretKey =
        Environment.GetEnvironmentVariable("PLAYFAB_SECRET_KEY", EnvironmentVariableTarget.Process);

#endif
    PlayFabSettings.staticSettings.TitleId =
        Environment.GetEnvironmentVariable("PLAYFAB_TITLE_ID", EnvironmentVariableTarget.Process);
    PlayFab.EconomyModels.EntityKey gameEntityKey = new()
    {
        Type = "title",
        Id = PlayFabSettings.staticSettings.TitleId
    };

    PlayFabResult<GetEntityTokenResponse> gameTokenRequest = null;
    try
    {
        gameTokenRequest = await PlayFabAuthenticationAPI.GetEntityTokenAsync(new GetEntityTokenRequest()
        {
            CustomTags = new Dictionary<string, string>
            {
#if ENABLE_PLAYFABSERVER_API
                { "server", systemGUID }
#endif
            }
        });
        if (gameTokenRequest.Error != null)
        {
            throw new Exception(gameTokenRequest.Error.GenerateErrorReport());
        }
    }
    catch (Exception e)
    {
        Console.WriteLine(string.Format("PlayFab Auth Error: {0}", e));
        return;
    }

    PlayFabAuthenticationContext gameAuthContext = new()
    {
        EntityToken = gameTokenRequest.Result.EntityToken,
    };
}

ヒント

タイトルの管理者として呼び出すとき、つまり、ユーザーログインからの SessionTicket を使用せずに呼び出すときは、誰が電話をかけているかを記録する CustomTags エントリを含めることがベストプラクティスです。サーバー、または自動スクリプト。これにより、PlayFab ログをクエリするときに変更を追跡し、問題を特定することが容易になります。

ステップ 2 - カタログ設定を構成する

カタログ設定には、コンテンツタイプからユーザー生成コンテンツまで、さまざまな構成が含まれます。これらはすべて API を通じて更新および取得でき、ゲームマネージャーでその多くを簡単に視覚化できます。

ゲームマネージャー
API

[ゲームマネージャー]で、⚙️ タイトル設定>エコノミーに移動します。
[カタログ (V2)] タブで、[カタログ設定] に移動します。
既定の コンテンツタイプ を作成します (「ゲームアイテム」タイプの作成から始めるとよいでしょう)。

Catalog/GetCatalogConfig メソッドを呼び出してから、カタログタイプを含むカタログ ContentTypes 配列を UpdateCatalogConfig します。

curl \
  -H "X-SecretKey: {{SecretKey}}" \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/GetCatalogConfig \
  -d "{\"CustomTags\": {\"user\": \"{{Email}}\"}}"

curl \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/UpdateCatalogConfig \
  -d "{\"Config\": {{{CatalogConfig}}}, \"CustomTags\": {\"user\": \"{{Email}}\"}}"

カタログと UGC のいくつかのコンテンツタイプを含むタイトルの戻りペイロードの例:

{
    "code": 200,
    "status": "OK",
    "data": {
        "Config": {
            "IsCatalogEnabled": true,
            "AdminEntities": [...],
            "Catalog": {
                "ContentTypes": [
                    "gameitem",
                    "enemy",
                    "weapon",
                    "armor",
                    "levelupstats"
                ],
                "Tags": [...]
            },
            "DeepLinkFormats": [],
            "DisplayPropertyIndexInfos": [
                {
                    "Name": "TestSearchable",
                    "Type": "SearchString"
                }
            ],
            "ReviewerEntities": [],
            "UserGeneratedContent": {
                "ContentTypes": [
                    "weapon",
                    "armor"
                ],
                "Tags": [...]
            },
            ...
        }
    }
}

ステップ 3 - アイテムをカタログに公開する

エコノミー>カタログ (V2) に移動します。

[アイテム] タブで、[新しいアイテム] を選択します。

必要なメタデータを入力します。必須のプロパティは 4 つだけです (作成者タイプ、タイトル、開始日、コンテンツタイプ)。 [発行]を選択します。

ヒント

クリエイタータイプのデフォルトは「タイトル」ですが、プレイヤーがゲーム用のアイテムを作成している場合もあります。その場合は "title_player_account" を選択します。 [JSON の編集] オプションのあるフィールドは、デフォルトで「ニュートラル」に設定されるローカリゼーション言語などのメタデータによってキー設定されます。すべての日付は UTC です。

{
  "NEUTRAL": "My Game Item",
  "en-US": "My Game Item"
}

CreateDraftItem エンドポイントを呼び出して、「ドラフト」カタログアイテムを作成します。

X-EntityToken ヘッダー内の EntityToken (GetEntityToken または他の PlayFab login 呼び出しから)
アイテムの CreatorEntity.Id の Playfab タイトル ID

curl \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/CreateDraftItem \
  -d "{{Data}}"

データ：

{
  "Item": {
    "CreatorEntity": {
      "Id": "{{TitleID}}",
      "Type": "title"
    },
    "Type": "catalogItem",
    "ContentType": "gameitem",
    "Title": {
      "NEUTRAL": "My Amazing Fire Sword",
      "en-US": "My Lit Lit Sword"
    },
    "StartDate": "2023-07-27T00:00:00.000Z",
    "Tags": [
      "weapon"
    ]
  },
  "Publish": true,
  "CustomTags": {
    "user": "{{Email}}"
  }
}

private static async Task PlayFabEconomyv2QuickStart()
{
    // Continued from above example...
    CreateDraftItemRequest gameFireItem = new()
    {
        AuthenticationContext = gameAuthContext,
        Item = new CatalogItem()
        {
            CreatorEntity = gameEntityKey,
            Type = "catalogItem",
            ContentType = "gameitem",
            Title = new Dictionary<string, string>
            {
                { "NEUTRAL", "My Amazing Fire Sword" },
                { "en-US", "My Lit Lit Sword" }
            },
            StartDate = DateTime.Now,
            Tags = new List<string>
            {
              "weapon"
            }
        },
        Publish = true,
        CustomTags = new Dictionary<string, string>
        {
            { "server", systemGUID }
        }
    };
    PlayFabResult<CreateDraftItemResponse> gameDraftItemResponse = null;
    try
    {
        gameDraftItemResponse = await PlayFabEconomyAPI.CreateDraftItemAsync(gameFireItem);
        if (gameDraftItemResponse.Error != null)
        {
            throw new Exception(gameDraftItemResponse.Error.GenerateErrorReport());
        }
    }
    catch (Exception e)
    {
        Console.WriteLine(string.Format("PlayFab CreateDraftItem Error: {0}", e));
        return;
    }
    Console.WriteLine(string.Format("PlayFab CreateDraftItem Success: {0}",
        JsonConvert.SerializeObject(gameDraftItemResponse.Result, Formatting.Indented)));
}

注意

アイテムをドラフト状態にする必要はありません。ドラフトは、メタデータを一定期間反復することが予想される場合に使用します。 "publish” パラメータをサポートしています。”true"に設定すると、アイテムがすぐに公開されます。これにより、パターンによっては通話量をいくらか節約できる可能性があります。

アイテムがドラフトになったら、PublishDraftItem エンドポイントを使用してアイテムを「公開」状態にプッシュできます (このステップは GameManager で非表示に処理されます)。アイテムが公開されると、検索可能になり、一般に公開されます。公開するには、CreateDraftItem 応答から返された ItemId を使用する必要があります。

ステップ 4 - 検索を実行する

Publish 呼び出しが成功すると、以前に公開された ItemId と SearchItems エンドポイントを使用してアイテムを検索できます。カタログ/検索 API は、API に提供された一連のパラメーターを使用して、公開されたカタログに対して検索を実行し、ページ分割された一連の結果を返します。

ゲームマネージャー
API

ゲームマネージャーの検索は一目瞭然で、カタログ v2 の各ページにあります。 公開済みフィルタとドラフトフィルタが上部にあります。 [検索] ボタンの横にある [フィルタ (ファネル)] アイコンを選択すると、フィルタのリストが表示されます。 Enter ODATA filter を選択して OData フィルターを追加します。

curl \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/SearchItems \
  -d "{{Data}}"

{
  "Search": "Fire",
  "Filter": "tags/any(t:t eq 'desert') and contentType eq 'gameitem'",
  "OrderBy": "lastModifiedDate asc",
  "ContinuationToken": "abc=",
  "Count": 2
}

返された ID をこのクイックスタートで後で使用するために保存します。

注意

カタログ/検索フィルタ、orderBy、および選択フィールドは、クエリ標準として OData を使用します。

パート 2: 在庫と仮想通貨の概要

インベントリアイテムと仮想通貨は、PlayFab がプレーヤーエンティティに対してサポートする仮想商品の 2 つのゲーム内「バケツ」です。プロセスは以下のとおりです。

初期仮想通貨を設定する
仮想通貨コストのアイテムを作成する
プレイヤーのインベントリにアイテムを追加します

ステップ 1: 通貨の作成

仮想通貨は、ゲーム内のエコノミーの基礎となります。プレイヤーとキャラクターはこれらの通貨を付与され、それを使用してアイテムを購入またはトレードできます。

アイテムには仮想通貨または実際のお金で価格を設定できます。各タイトルで、複数の任意の仮想通貨をサポートできます。通貨は、ゲームに必要な交換媒体 (ゴールド、宝石、ハート、星間クレジットなど) を実装する柔軟性を提供します。

ゲームマネージャー
API

ゲームマネージャーを開き、エコノミー>カタログ (V2) に移動します。
[通貨] タブを選択します。
[新しい通貨] を選択し、開始日、人間が判読できる "ニュートラル" キーのタイトルを設定し、[フレンドリ ID] フィールドに、この通貨の一意の通貨コードを入力します。
[下書きとして保存] を選択します。アイテム ID はドラフト通貨コードとして使用されます。
通貨リストで [ドラフト] フィルタをクリックして選択し、新しい通貨を表示します。
通貨を再度編集し、[保存して公開] を選択します。フレンドリー ID は公開通貨コードとして使用されます。

以下を使用して、タイプを「currency」に設定して CreateDraftItem エンドポイントを呼び出し、ドラフト通貨カタログアイテムを作成します。

カタログ権限を持つ EntityToken
アイテム「Creator」としての Entity.Id
Playfab タイトル ID
アイテムは「通貨」タイプのバンドルであり、タイトルと説明が含まれている必要があります。

CreateDraftItem から返された ItemId を使用して PublishItem を呼び出します。

curl \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/CreateDraftItem \
  -d "{{Data}}"

データ：

{ 
  "Item": {
    "CreatorEntity": {
      "Id": "{{TitleID}}",
      "Type": "title"
    },
    "Type": "currency",
    "ContentType": "gameitem",
    "AlternateIds": [
      { 
        "Type": "FriendlyId",
        "Value": "TC"
      } 
    ],
    "Title": {
      "NEUTRAL": "My Amazing Test Currency",
      "en-US": "My Test Coin"
    },
    "StartDate": "2023-07-27T00:00:00.000Z"
  },
  "Publish": true,
  "CustomTags": {
    "user": "{{Email}}"
  }
}

ヒント

「通貨」タイプのカタログ/検索では、定義したすべての通貨が返されます。

エンティティプレーヤーが購入するには仮想通貨が必要です。

GameManager を開き、[プレーヤー] に移動し、[検索] を選択してプレーヤーのリストを取得します。
通貨を付与したいプレイヤー ID を選択します。
[インベントリ (V2) ] タブを選択します。
「通貨」にフィルタをかけて [入力]、[複数の項目を選択] を選択すると、通貨の完全なリストが表示されます。
作成した通貨を選択し、エンティティ プレーヤーの新しい金額を入力します。
[保存] を選択します。

Warning

現在、プレイヤーの通貨付与を公開するページは GameManager にありません。ロードマップを参照してください。

注意

AddInventoryItems はタイトル管理者の呼び出しとみなされ、通常はゲームクライアントによって直接呼び出されるものではありません。

ステップ 3 - カタログアイテムを更新する

アイテムを仮想通貨で購入できるようにするには、アイテムに通貨価値が必要です。

GameManager
API

ゲームマネージャーを開き、[エコノミー] に移動します。
[カタログ (V2)] タブを選択し、[公開済み] アイテムにフィルタリングされていることを確認します。
先ほど作成したアイテムのタイトルを選択します。
[下書きアイテムを編集] を選択します。
[➕ 新しい価格を追加] を選択し、作成した通貨アイテムを選択して [金額] を設定します。 [追加] を選択して完了します。
[保存して公開] を選択します。

GetDraftItem エンドポイントを呼び出して、カタログアイテムのドラフトを取得します。次に、以下を使用して UpdateDraftItem エンドポイントで下書きを更新します。

X-EntityToken ヘッダー内の EntityToken (GetEntityToken または他の PlayFab login 呼び出しから)
アイテムの EntityKey.Id 内の以前の呼び出しからの Entity.Id

curl \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/GetDraftItem \
  -d "{{Data}}"

データ：

{
  "Id": "{{EntityID}}",
  "CustomTags": {
    "user": "{{Email}}"
  }
}

curl \
  -H "X-EntityToken: {{EntityToken}}" \
  -H "Content-Type: application/json" \
  -X POST https://{{TitleId}}.playfabapi.com/Catalog/UpdateDraftItem \
  -d "{{Data}}"

{
  "Item": {
    "Id": "{{EntityID}}",
    "CreatorEntity": {
      "Id": "{{TitleID}}",
      "Type": "title"
    },
    "Type": "catalogItem",
    "ContentType": "gameitem",
    "Title": {
      "NEUTRAL": "My Amazing Fire Sword",
      "en-US": "My Lit Lit Sword"
    },
    "StartDate": "2023-07-27T00:00:00.000Z",
    "Tags": [
      "weapon"
    ]
    "PriceOptions": {
      "Prices": [
        {
          "Amounts": [
            {
              "ItemId": "{{CurrencyID}}",
              "Amount": 15
            }
          ]
        }
      ]
    }
  },
  "Publish": true,
  "CustomTags": {
    "user": "{{Email}}"
  }
}

Publish を true に設定しない場合は、PublishDraftItem を使用して公開状態にプッシュする必要があります。アイテムが公開されると、検索可能になり、一般に公開されます。公開するには、GetDraftItem 応答から返された「itemId」を使用する必要があります。

次の方法で共有

カタログ v2 クイックスタート

パート 1: カタログの概要

ステップ 1 – 権限を取得する

ステップ 2 - カタログ設定を構成する

ステップ 3 - アイテムをカタログに公開する

ステップ 4 - 検索を実行する

パート 2: 在庫と仮想通貨の概要

ステップ 1: 通貨の作成

ステップ 2 - 通貨の付与

ステップ 3 - カタログアイテムを更新する

関連項目

フィードバック

その他のリソース

次の方法で共有

カタログ v2 クイックスタート

パート 1: カタログの概要

ステップ 1 – 権限を取得する

ステップ 2 - カタログ設定を構成する

ステップ 3 - アイテムをカタログに公開する

ステップ 4 - 検索を実行する

パート 2: 在庫と仮想通貨の概要

ステップ 1: 通貨の作成

ステップ 2 - 通貨の付与

ステップ 3 - カタログ アイテムを更新する

フィードバック

その他のリソース

ステップ 3 - カタログアイテムを更新する