Edit

Catalog v2 quickstart

  • Article

Important

Economy v2 is now Generally Available. For support and feedback, go to the PlayFab Forum.

After becoming familiar with Game Manager, you can:

  1. Set up a v2 Catalog's permissions, settings, and items.
  2. Set up Receipt Validation
  3. Walk through purchasing an item

See the Unity-specific Tutorial for a detailed walkthrough in Unity.

Part 1: Catalog overview

Step 1 – Get permissions

The first step is to enable the catalog in the settings page in the Game Manager UI under ⚙️ Title Settings > Economy (V2). You can use the UpdateCatalogConfig API and set the IsCatalogEnabled flag to true.

To interact with the Catalog, you either need to Log into GameManger and use the site tools, or get an Entity Token for using the APIs. The easiest way to get an entity token is with the GetEntityToken API.

Note

To call the API as an admin or authoritative service, which you will need to do before you create your first Catalog item, you’ll need to include an X-SecretKey header with a title secret key. You can create title secret keys in the Game Manager UI under ⚙️ Title Settings > Secret Keys.

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

Tip

It's best practice when calling as an Admin for a Title, a.k.a. without a SessionTicket from a user login, to include a CustomTags entry logging who is making the call - whether it's you, a server, or an automated script. This makes it easier to trace changes and identify issues when querying your PlayFab logs.

Step 2 - Configure your Catalog Settings

Catalog Settings include many different configurations, from Content Types to User-Generated Content. You can update and retrieve them all through the API, and easily visualize many of them in Game Manager.

  1. In Game Manager, navigate to ⚙️ Title Settings > Economy.
  2. Under the Catalog (V2) tab, go to Catalog Settings
  3. Create a default Content Type (creating a "Game Item" type is a good place to start).

Step 3 - Publish an Item to the Catalog

Navigate to Economy > Catalog (V2).

Under the Items tab, select New Item.

Fill in the required metadata – there are only four required properties (Creator Type, Title, Start date, and Content type). Select Publish.

Tip

Creator Type defaults to "title" - although there may be instances where Players are creating items for your game. In that case, you would select "title_player_account". Fields with the Edit JSON option are keyed by metadata such as the localization language which defaults to "neutral". All dates are UTC.

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

Note

Putting the item into a Draft state is not required – Draft is meant for when you expect to iterate on the metadata for some period of time. We support the parameter "publish”, that when set to "true" will publish the item immediately. This could save you some call volume depending on your pattern.

Once an Item is in Draft, you can then push it to a ‘Published’ state using the PublishDraftItem endpoint (this step is handled invisibly in GameManager). Once an item is Published, it's searchable and available publicly. You need to use the ItemId returned from the CreateDraftItem response in order to publish.

Step 4 - Do a search

Once the Publish call succeeds, the Item can be searched for using the previously published ItemId and SearchItems endpoint. The Catalog/Search API executes a search against the published catalog using a set of parameters provided to the API, returning a set of paginated results.

Game Manager search is self-explanatory and exists on each Catalog v2 page. Published and Draft filters are at the top. Select the Filters (Funnel) icon next to the Search button to see the list of filters. Select Enter ODATA filter to add an OData filter.

Note

Catalog/search filter, orderBy, and select fields use OData as the query standard.

Part 2: Inventory and Virtual Currencies overview

Inventory Items and Virtual Currencies are the two in-game ‘buckets’ of virtual goods that PlayFab supports for Player Entities. The process is:

  1. Set up an initial Virtual Currency
  2. Create an Item with a Virtual Currency Cost
  3. Add the item to a player's Inventory

Step 1: Creating a Currency

Virtual currencies are the foundation of in-game economies. Players and characters can be granted these currencies, which can then be used to buy or trade items.

Items can have a cost in either a virtual currency or real money. Each title can support multiple arbitrary virtual currencies. Currencies provide flexibility for your game to implement whatever medium of exchange you desire (for example, gold, gems, hearts, or interstellar credits).

  1. Open Game Manager and go to Economy > Catalog (V2).
  2. Select the Currency tab.
  3. Choose New Currency, setting the Start date, a human-readable Title for the "neutral" key, and in the Friendly ID field, enter a unique currency code for this currency.
  4. Select Save as draft. The Item ID is used as a draft currency code.
  5. View your new currency by clicking selecting the Draft filter in the currency list.
  6. Edit the currency again and select Save and publish. The Friendly ID is used as a published currency code.

Tip

A Catalog/Search for type 'currency' will return all of the currencies you have defined.

Step 2 - Granting Currencies

Your entity player needs virtual currency in order to make a Purchase.

  1. Open GameManager, navigate to Players, and select Search to retrieve the list of players.
  2. Select the Player ID you wish to grant currency to.
  3. Select the Inventory (V2) tab.
  4. Filter to "Currency" Type and select Pick multiple items to view the full list of currencies.
  5. Choose the Currency you created and enter a new amount for the Entity Player.
  6. Select Save.

Warning

The pages exposing player Currency Grants are not in GameManager today. See the Roadmap.

Note

AddInventoryItems is considered a Title admin call, and is normally not something called directly by the game client.

Step 3 - Update a Catalog Item

An item must have a currency value in order for it to be purchasable with virtual currency.

  1. Open Game Manager and navigate to Economy.
  2. Select the Catalog (V2) tab and ensure you're filtered to Published items.
  3. Select the title of the item you created earlier.
  4. Select Edit draft item.
  5. Select ➕ Add new price and set an Amount by selecting the Currency item you created. Select Add to finish.
  6. Select Save and Publish.