Início rápido do Catalog v2

O Economy v2 agora está em disponibilidade geral. Para obter suporte e enviar comentários, acesse o Fórum do PlayFab.

Depois de se familiarizar com o Game Manager, você pode:

Configurar as permissões, as configurações e os itens de um Catalog v2.
Configurar a validação de recibos
Percorrer a compra de um item

Consulte o tutorial específico do Unity para obter um passo a passo detalhado no Unity.

Parte 1: Visão geral do catálogo

Etapa 1 – Obter permissões

A primeira etapa é habilitar o catálogo na página de configurações da interface do Game Manager em ⚙️ Title Settings > Economy (V2). Você pode usar a API UpdateCatalogConfig e definir o sinalizador IsCatalogEnabled como true. Para interagir com o catálogo, você precisa entrar no Game Manager e usar as ferramentas do site ou obter um token de entidade para usar as APIs. A maneira mais fácil de obter um token de entidade é com a API GetEntityToken.

Para chamar a API como administrador ou serviço autoritativo, o que você precisará fazer antes de criar seu primeiro item de catálogo, você precisará incluir um cabeçalho X-SecretKey com uma chave secreta do título. Você pode criar chaves secretas do título na interface do Game Manager em ⚙️ 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 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,
    };
}

Ao fazer chamadas como administrador de um título, ou seja, sem um SessionTicket de login de um usuário, a prática recomendada é incluir uma entrada CustomTags registrando quem está fazendo a chamada, seja você, um servidor ou um script automatizado. Isso facilita o rastreamento de alterações e a identificação de problemas ao consultar seus logs do PlayFab.

Etapa 2 - Definir as configurações do catálogo

As configurações do catálogo incluem muitas configurações diferentes, de tipos de conteúdo a conteúdo gerado pelo usuário. Você pode atualizar e recuperar todas elas por meio da API e visualizar facilmente muitas delas no Game Manager.

Game Manager

No Game Manager, navegue até ⚙️ Title Settings > Economy.
Na guia Catalog (V2), acesse Catalog Settings
Crie um Content Type padrão (criar um tipo “Game Item” é um bom ponto de partida).

API

Chame o método Catalog/GetCatalogConfig e, em seguida, use UpdateCatalogConfig para atualizar a matriz ContentTypes do catálogo com um tipo de catálogo.

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

Exemplo de payload retornado para um título com alguns tipos de conteúdo para Catalog e 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": [...]
            },
            ...
        }
    }
}

Etapa 3 - Publicar um item no catálogo

GameManager

Navegue até Economy > Catalog (V2). Na guia Items, selecione New Item. Preencha os metadados obrigatórios – há apenas quatro propriedades obrigatórias (Creator Type, Title, Start date e Content type). Selecione Publish.

O Creator Type assume como padrão “title”, embora possa haver casos em que jogadores criam itens para o seu jogo. Nesse caso, você selecionaria “title_player_account”. Os campos com a opção Edit JSON são indexados por metadados, como o idioma de localização, que assume como padrão “neutral”. Todas as datas estão em UTC.

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

API

Crie um item de catálogo em “rascunho” chamando o ponto de extremidade CreateDraftItem:

O EntityToken (de GetEntityToken ou de outra chamada login do PlayFab) no cabeçalho X-EntityToken
A ID do título do PlayFab em CreatorEntity.Id do item

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

Dados:

{
  "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()
{
    // 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)));
}

Colocar o item em estado de rascunho não é obrigatório – o rascunho se destina aos casos em que você espera iterar nos metadados por algum tempo. Damos suporte ao parâmetro “publish”, que, quando definido como “true”, publica o item imediatamente. Isso pode economizar algum volume de chamadas, dependendo do seu padrão.

Quando um item estiver em rascunho, você poderá enviá-lo para o estado ‘Published’ usando o ponto de extremidade PublishDraftItem (essa etapa é tratada de forma invisível no Game Manager). Depois que um item é publicado, ele pode ser pesquisado e fica disponível publicamente. Você precisa usar o ItemId retornado na resposta de CreateDraftItem para publicar.

Etapa 4 - Fazer uma pesquisa

Depois que a chamada de publicação for bem-sucedida, o item poderá ser pesquisado usando o ItemId publicado anteriormente e o ponto de extremidade SearchItems. A API Catalog/Search executa uma pesquisa no catálogo publicado usando um conjunto de parâmetros fornecidos à API e retorna um conjunto de resultados paginados.

Game Manager

A pesquisa do Game Manager é autoexplicativa e existe em cada página do Catalog v2. Os filtros Published e Draft ficam na parte superior. Selecione o ícone Filters (Funnel) ao lado do botão Search para ver a lista de filtros. Selecione Enter ODATA filter para adicionar um filtro OData.

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
}

Salve a ID retornada para usar mais adiante neste início rápido.

Os campos filter, orderBy e select de Catalog/search usam o OData como padrão de consulta.

Parte 2: Visão geral de inventário e moedas virtuais

Itens de inventário e moedas virtuais são os dois ‘compartimentos’ de bens virtuais do jogo aos quais o PlayFab dá suporte para entidades de jogador. O processo é:

Configurar uma moeda virtual inicial
Criar um item com um custo em moeda virtual
Adicionar o item ao inventário de um jogador

Etapa 1: Criar uma moeda

As moedas virtuais são a base das economias dos jogos. Jogadores e personagens podem receber essas moedas, que podem então ser usadas para comprar ou trocar itens. Os itens podem ter um custo em moeda virtual ou em dinheiro real. Cada título pode dar suporte a várias moedas virtuais arbitrárias. As moedas oferecem flexibilidade para que seu jogo implemente qualquer meio de troca que você desejar (por exemplo, ouro, gemas, corações ou créditos interestelares).

Game Manager

Abra o Game Manager e acesse Economy > Catalog (V2).
Selecione a guia Currency.
Escolha New Currency, definindo a Start date, um Title legível por humanos para a chave “neutral” e, no campo Friendly ID, insira um código de moeda exclusivo para essa moeda.
Selecione Save as draft. A Item ID é usada como código de moeda de rascunho.
Veja sua nova moeda selecionando o filtro Draft na lista de moedas.
Edite a moeda novamente e selecione Save and publish. A Friendly ID é usada como código de moeda publicado.

API

Crie um item de catálogo de moeda em rascunho chamando o ponto de extremidade CreateDraftItem com o tipo definido como “currency”, usando:

Um EntityToken com permissões de catálogo
O Entity.Id como ‘Creator’ do item
A ID do título do PlayFab
O item deve ser um Bundle do tipo ‘Currency’ e conter um Title e uma Description

Chame PublishItem com o ItemId retornado por CreateDraftItem.

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

Dados:

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

Uma Catalog/Search pelo tipo ‘currency’ retornará todas as moedas que você definiu.

Etapa 2 - Conceder moedas

Game Manager

Sua entidade de jogador precisa de moeda virtual para fazer uma compra.

Abra o Game Manager, navegue até Players e selecione Search para recuperar a lista de jogadores.
Selecione a Player ID à qual você deseja conceder moeda.
Selecione a guia Inventory (V2).
Filtre pelo Type “Currency” e selecione Pick multiple items para ver a lista completa de moedas.
Escolha a Currency que você criou e insira uma nova quantidade para a entidade Player.
Selecione Save.

As páginas que expõem as concessões de moeda aos jogadores não estão no Game Manager atualmente.

API

Você pode chamar AddInventoryItems para adicionar moeda à carteira de uma entidade. Por padrão, você precisa usar a autenticação de entidade no nível do título para adicionar moedas virtuais arbitrariamente ao inventário de um jogador.

AddInventoryItems é considerada uma chamada de administrador do título e normalmente não é chamada diretamente pelo cliente do jogo.

Etapa 3 - Atualizar um item de catálogo

Um item deve ter um valor em moeda para poder ser comprado com moeda virtual.

GameManager

Abra o Game Manager e navegue até Economy.
Selecione a guia Catalog (V2) e verifique se o filtro está definido para itens Published.
Selecione o título do item que você criou anteriormente.
Selecione Edit draft item.
Selecione ➕ Add new price e defina um Amount selecionando o item de moeda que você criou. Selecione Add para concluir.
Selecione Save and Publish.

API

Obtenha o rascunho do seu item de catálogo chamando o ponto de extremidade GetDraftItem. Em seguida, atualize o rascunho com o ponto de extremidade UpdateDraftItem usando:

O EntityToken (de GetEntityToken ou de outra chamada login do PlayFab) no cabeçalho X-EntityToken
O Entity.Id da chamada anterior em EntityKey.Id do item

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

Dados:

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

Se você não definir Publish como true, deverá enviá-lo para o estado publicado usando PublishDraftItem. Depois que um item é publicado, ele pode ser pesquisado e fica disponível publicamente. Você precisa usar o “itemId” retornado na resposta de GetDraftItem para publicar.

XBOX Services

PlayFab

Início rápido

Início rápido do Catalog v2

Parte 1: Visão geral do catálogo

Etapa 1 – Obter permissões

API

C# SDK

Etapa 2 - Definir as configurações do catálogo

Game Manager

API

Etapa 3 - Publicar um item no catálogo

GameManager

API

C# SDK

Etapa 4 - Fazer uma pesquisa

Game Manager

API

Parte 2: Visão geral de inventário e moedas virtuais

Etapa 1: Criar uma moeda

Game Manager

API

Etapa 2 - Conceder moedas

Game Manager

API

Etapa 3 - Atualizar um item de catálogo

GameManager

API

Confira também

​Início rápido do Catalog v2

​Parte 1: Visão geral do catálogo

​Etapa 1 – Obter permissões

​API

​C# SDK

​Etapa 2 - Definir as configurações do catálogo

​Game Manager

​API

​Etapa 3 - Publicar um item no catálogo

​GameManager

​API

​C# SDK

​Etapa 4 - Fazer uma pesquisa

​Game Manager

​API

​Parte 2: Visão geral de inventário e moedas virtuais

​Etapa 1: Criar uma moeda

​Game Manager

​API

​Etapa 2 - Conceder moedas

​Game Manager

​API

​Etapa 3 - Atualizar um item de catálogo

​GameManager

​API

​Confira também

Início rápido do Catalog v2

Parte 1: Visão geral do catálogo

Etapa 1 – Obter permissões

API

C# SDK

Etapa 2 - Definir as configurações do catálogo

Game Manager

API

Etapa 3 - Publicar um item no catálogo

GameManager

API

C# SDK

Etapa 4 - Fazer uma pesquisa

Game Manager

API

Parte 2: Visão geral de inventário e moedas virtuais

Etapa 1: Criar uma moeda

Game Manager

API

Etapa 2 - Conceder moedas

Game Manager

API

Etapa 3 - Atualizar um item de catálogo

GameManager

API

Confira também