Catalog v2 quickstart

Important

Economy v2.0 Public Preview has released. Use these features to participate in the active development of our latest code, and provide feedback to the developers via the PlayFab Forum.

Assuming you've already worked through the Getting started for developers, you'll want to:

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

Part 1: Catalog overview

Step 1 – Get permissions

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.

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. In order to use them, you:

  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 Title Settings
  2. Select the Currency tab
  3. Choose New Currency, setting the Currency code and the Display/Friendly name
  4. Select Save Currency

Tip

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

Step 2 - Granting Currencies

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

  1. Open GameManager, navigate to Players, and select the Player ID you wish to grant currency to
  2. Select the Inventory (V2) tab.
  3. Choose the Currency you created and enter a new amount for the Entity Player.
  4. 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 purchaseable with virtual currency.

  1. Open Game Manager and navigate to Economy.
  2. Select the Catalog (v2) tab and sure you are viewing 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.