Catalog v2 のクイックスタート

Economy v2 が一般提供 (GA) されました。サポートとフィードバックについては、PlayFab フォーラムを参照してください。

Game Manager に慣れたら、次のことができます。

v2 カタログの権限、設定、アイテムをセットアップします。
レシート検証をセットアップします。
アイテムの購入を試します。

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

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

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

最初のステップは、Game Manager UI の設定ページ ⚙️ Title Settings > Economy (V2) でカタログを有効にすることです。UpdateCatalogConfig API を使用して IsCatalogEnabled フラグを true に設定できます。カタログとやり取りするには、Game Manager にログインしてサイトツールを使用するか、API を使用するために Entity Token を取得する必要があります。エンティティトークンを取得する最も簡単な方法は、GetEntityToken API です。

管理者または権威あるサービスとして API を呼び出すには (最初のカタログアイテムを作成する前にこれを行う必要があります)、X-SecretKey ヘッダーにタイトルシークレットキーを含める必要があります。タイトルシークレットキーは、Game Manager UI の ⚙️ Title Settings > Secret Keys で作成できます。

API

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

C# SDK

// ENABLE_PLAYFABSERVER_API シンボルは、これが管理者レベルのゲーム サーバーであり、ゲーム クライアントではないことを示します。
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 を通じてすべてを更新および取得でき、多くは Game Manager で簡単に可視化できます。

Game Manager

Game Manager で、⚙️ Title Settings > Economy に移動します。
Catalog (V2) タブで Catalog Settings に移動します。
デフォルトの コンテンツタイプ を作成します (“Game Item” タイプを作成することが良い出発点です)。

API

Catalog/GetCatalogConfig メソッドを呼び出し、次に UpdateCatalogConfig でカタログの ContentTypes 配列にカタログタイプを追加します。

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 - アイテムをカタログに公開する

Game Manager

Economy > Catalog (V2) に移動します。 Items タブの下で New Item を選択します。必要なメタデータを入力します。必須のプロパティは 4 つ (Creator Type、Title、Start date、Content type) のみです。Publish を選択します。

Creator Type のデフォルトは “title” です。ただし、プレイヤーがゲーム用にアイテムを作成する場合もあります。その場合は “title_player_account” を選択します。Edit JSON オプションがあるフィールドは、ローカライゼーション言語 (デフォルトは “neutral”) などのメタデータでキー付けされます。すべての日付は UTC です。

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

API

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

C# SDK

private static async Task PlayFabEconomyv2QuickStart()
{
    // 上記の例の続き...
    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 エンドポイントを使用して ‘公開済み’ 状態にプッシュできます (このステップは Game Manager では非表示で処理されます)。アイテムが公開されると、検索可能になり、公開で利用可能になります。公開するには、CreateDraftItem レスポンスから返された ItemId を使用する必要があります。

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

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

Game Manager

Game Manager の検索は自明で、各 Catalog v2 ページに存在します。Published と Draft のフィルターが上部にあります。Search ボタンの横にある Filters (Funnel) アイコンを選択すると、フィルターのリストが表示されます。OData フィルターを追加するには、Enter ODATA filter を選択します。

API

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 を保存しておきます。

Catalog/search の filter、orderBy、select フィールドは、クエリ標準として OData を使用します。

パート 2: インベントリと仮想通貨の概要

インベントリアイテムと仮想通貨は、PlayFab がプレイヤーエンティティ用にサポートしているゲーム内の 2 つの仮想商品 “バケット” です。プロセスは次のとおりです。

初期の仮想通貨をセットアップする
仮想通貨コストを持つアイテムを作成する
アイテムをプレイヤーのインベントリに追加する

ステップ 1: 通貨を作成する

仮想通貨は、ゲーム内経済の基盤です。プレイヤーやキャラクターにこれらの通貨を付与でき、それを使用してアイテムを購入したり交換したりできます。アイテムには、仮想通貨または実際のお金のコストを設定できます。各タイトルは、任意の複数の仮想通貨をサポートできます。通貨は、ゲームが希望する交換手段 (たとえば、ゴールド、ジェム、ハート、星間クレジット) を実装するための柔軟性を提供します。

Game Manager

Game Manager を開き、Economy > Catalog (V2) に移動します。
Currency タブを選択します。
New Currency を選択し、Start date、“neutral” キーの人間が読める Title を設定し、Friendly ID フィールドにこの通貨の一意の通貨コードを入力します。
Save as draft を選択します。Item ID は下書き通貨コードとして使用されます。
通貨リストで Draft フィルターを選択して、新しい通貨を表示します。
通貨を再度編集し、Save and publish を選択します。Friendly ID は公開通貨コードとして使用されます。

API

タイプを “currency” に設定した CreateDraftItem エンドポイントを次を使用して呼び出し、下書き通貨カタログアイテムを作成します。

カタログ権限を持つ EntityToken
アイテムの ‘Creator’ として Entity.Id
PlayFab のタイトル ID
アイテムは ‘Currency’ タイプのバンドルで、Title と Description を含む必要があります

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

タイプ ‘currency’ の Catalog/Search により、定義したすべての通貨が返されます。

ステップ 2 - 通貨を付与する

Game Manager

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

Game Manager を開き、Players に移動し、Search を選択してプレイヤーのリストを取得します。
通貨を付与するプレイヤー ID を選択します。
Inventory (V2) タブを選択します。
Type で “Currency” にフィルターし、Pick multiple items を選択して通貨の完全なリストを表示します。
作成した通貨を選択し、エンティティ プレイヤー の新しい数量を入力します。
Save を選択します。

プレイヤーの通貨付与を公開するページは、現時点では Game Manager に存在しません。

API

AddInventoryItems を呼び出して、エンティティのウォレットに通貨を追加できます。デフォルトでは、プレイヤーのインベントリに任意の仮想通貨を追加するには、タイトルレベルのエンティティ認証を使用する必要があります。

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

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

仮想通貨で購入可能にするには、アイテムに通貨の値が必要です。

Game Manager

Game Manager を開き、Economy に移動します。
Catalog (V2) タブを選択し、Published アイテムでフィルターされていることを確認します。
先ほど作成したアイテムのタイトルを選択します。
Edit draft item を選択します。
➕ Add new price を選択し、作成した Currency アイテムを選択して Amount を設定します。Add を選択して完了します。
Save and Publish を選択します。

API

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” を使用する必要があります。

XBOX Services

PlayFab

クイックスタート

Catalog v2 のクイックスタート

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

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

API

C# SDK

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

Game Manager

API

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

Game Manager

API

C# SDK

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

Game Manager

API

パート 2: インベントリと仮想通貨の概要

ステップ 1: 通貨を作成する

Game Manager

API

ステップ 2 - 通貨を付与する

Game Manager

API

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

Game Manager

API

関連項目

​Catalog v2 のクイックスタート

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

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

​API

​C# SDK

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

​Game Manager

​API

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

​Game Manager

​API

​C# SDK

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

​Game Manager

​API

​パート 2: インベントリと仮想通貨の概要

​ステップ 1: 通貨を作成する

​Game Manager

​API

​ステップ 2 - 通貨を付与する

​Game Manager

​API

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

​Game Manager

​API

​関連項目

Catalog v2 のクイックスタート

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

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

API

C# SDK

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

Game Manager

API

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

Game Manager

API

C# SDK

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

Game Manager

API

パート 2: インベントリと仮想通貨の概要

ステップ 1: 通貨を作成する

Game Manager

API

ステップ 2 - 通貨を付与する

Game Manager

API

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

Game Manager

API

関連項目