Inicio rápido del catálogo v2

Economy v2 ya está disponible con carácter general. Para soporte y comentarios, vaya al foro de PlayFab.

Después de familiarizarse con Game Manager, puede:

Configurar los permisos, los ajustes y los artículos de un catálogo v2.
Configurar la validación de recibos
Recorrer el proceso de compra de un artículo

Consulte el tutorial específico de Unity para ver un recorrido detallado en Unity.

Parte 1: Información general del catálogo

Paso 1: Obtener permisos

El primer paso es habilitar el catálogo en la página de configuración de la interfaz de usuario de Game Manager, en ⚙️ Title Settings > Economy (V2). Puede usar la API UpdateCatalogConfig y establecer la marca IsCatalogEnabled en true. Para interactuar con el catálogo, debe iniciar sesión en Game Manager y usar las herramientas del sitio, u obtener un token de entidad para usar las API. La forma más sencilla de obtener un token de entidad es con la API GetEntityToken.

Para llamar a la API como administrador o servicio autoritativo, algo que tendrá que hacer antes de crear su primer artículo de catálogo, deberá incluir un encabezado X-SecretKey con una clave secreta del título. Puede crear claves secretas del título en la interfaz de usuario de Game Manager, en ⚙️ 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}}\"}}"

SDK de C#

// 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,
    };
}

Cuando se llama como administrador de un título, es decir, sin un SessionTicket procedente del inicio de sesión de un usuario, es una práctica recomendada incluir una entrada de CustomTags que registre quién realiza la llamada, ya sea usted, un servidor o un script automatizado. Esto facilita el seguimiento de los cambios y la identificación de problemas al consultar los registros de PlayFab.

Paso 2: Configurar los ajustes del catálogo

Los ajustes del catálogo incluyen muchas configuraciones distintas, desde los tipos de contenido hasta el contenido generado por usuarios. Puede actualizarlos y recuperarlos todos a través de la API, y visualizar fácilmente muchos de ellos en Game Manager.

Game Manager

En Game Manager, vaya a ⚙️ Title Settings > Economy.
En la pestaña Catalog (V2), vaya a Catalog Settings
Cree un Content Type predeterminado (crear un tipo “Game Item” es un buen punto de partida).

API

Llame al método Catalog/GetCatalogConfig y, a continuación, con UpdateCatalogConfig actualice la matriz ContentTypes del catálogo con un 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}}\"}}"

Ejemplo de carga de retorno para un título con algunos tipos de contenido para el catálogo y 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": [...]
            },
            ...
        }
    }
}

Paso 3: Publicar un artículo en el catálogo

Game Manager

Vaya a Economy > Catalog (V2). En la pestaña Items, seleccione New Item. Rellene los metadatos necesarios: solo hay cuatro propiedades obligatorias (Creator Type, Title, Start date y Content type). Seleccione Publish.

Creator Type tiene el valor predeterminado “title”, aunque puede haber casos en los que los jugadores creen artículos para su juego. En ese caso, seleccionaría “title_player_account”. Los campos con la opción Edit JSON se indexan mediante metadatos, como el idioma de localización, cuyo valor predeterminado es “neutral”. Todas las fechas están en UTC.

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

API

Cree un artículo de catálogo en estado “Draft” (borrador) llamando al punto de conexión CreateDraftItem con:

El EntityToken (de GetEntityToken u otra llamada login de PlayFab) en el encabezado X-EntityToken
El identificador de título de PlayFab en el CreatorEntity.Id del artículo

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

Datos:

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

SDK de C#

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)));
}

No es obligatorio poner el artículo en estado de borrador (Draft); el borrador está pensado para cuando espera iterar en los metadatos durante algún tiempo. Admitimos el parámetro “publish” que, cuando se establece en “true”, publica el artículo inmediatamente. Esto podría ahorrarle algo de volumen de llamadas según su patrón.

Una vez que un artículo está en borrador, puede pasarlo al estado “Published” (publicado) mediante el punto de conexión PublishDraftItem (este paso se gestiona de forma transparente en Game Manager). Una vez publicado un artículo, se puede buscar y está disponible públicamente. Debe usar el ItemId devuelto en la respuesta de CreateDraftItem para poder publicar.

Paso 4: Realizar una búsqueda

Una vez que la llamada de publicación se realiza correctamente, se puede buscar el artículo mediante el ItemId publicado anteriormente y el punto de conexión SearchItems. La API Catalog/Search ejecuta una búsqueda en el catálogo publicado con un conjunto de parámetros proporcionados a la API y devuelve un conjunto de resultados paginados.

Game Manager

La búsqueda de Game Manager es autoexplicativa y existe en cada página del catálogo v2. Los filtros Published y Draft están en la parte superior. Seleccione el icono de Filters (embudo) situado junto al botón Search para ver la lista de filtros. Seleccione Enter ODATA filter para agregar un 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
}

Guarde el identificador devuelto para usarlo más adelante en este inicio rápido.

Los campos filter, orderBy y select de Catalog/search usan OData como estándar de consulta.

Parte 2: Información general del inventario y las monedas virtuales

Los artículos de inventario y las monedas virtuales son los dos “cubos” de artículos virtuales del juego que PlayFab admite para las entidades de jugador. El proceso es el siguiente:

Configurar una moneda virtual inicial
Crear un artículo con un costo en moneda virtual
Agregar el artículo al inventario de un jugador

Paso 1: Crear una moneda

Las monedas virtuales son la base de las economías del juego. Se pueden conceder estas monedas a los jugadores y personajes, que después se pueden usar para comprar o intercambiar artículos. Los artículos pueden tener un costo en moneda virtual o en dinero real. Cada título puede admitir varias monedas virtuales arbitrarias. Las monedas proporcionan flexibilidad para que su juego implemente el medio de intercambio que desee (por ejemplo, oro, gemas, corazones o créditos interestelares).

Game Manager

Abra Game Manager y vaya a Economy > Catalog (V2).
Seleccione la pestaña Currency.
Elija New Currency, establezca la Start date, un Title legible para la clave “neutral” y, en el campo Friendly ID, escriba un código de moneda único para esta moneda.
Seleccione Save as draft. El Item ID se usa como código de moneda del borrador.
Vea la nueva moneda seleccionando el filtro Draft en la lista de monedas.
Edite la moneda de nuevo y seleccione Save and publish. El Friendly ID se usa como código de moneda publicado.

API

Cree un artículo de catálogo de moneda en borrador llamando al punto de conexión CreateDraftItem con el tipo establecido en “currency” y usando:

Un EntityToken con permisos de catálogo
El Entity.Id como “Creator” del artículo
El identificador de título de PlayFab
El artículo debe ser una agrupación de tipo “Currency” y contener un título y una descripción

Llame a PublishItem con el ItemId devuelto por CreateDraftItem.

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

Datos:

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

Una búsqueda de Catalog/Search del tipo “currency” devolverá todas las monedas que haya definido.

Paso 2: Conceder monedas

Game Manager

Su jugador de entidad necesita moneda virtual para poder realizar una compra.

Abra Game Manager, vaya a Players y seleccione Search para recuperar la lista de jugadores.
Seleccione el Player ID al que quiera conceder moneda.
Seleccione la pestaña Inventory (V2).
Filtre por el Type “Currency” y seleccione Pick multiple items para ver la lista completa de monedas.
Elija la moneda que creó y escriba una nueva cantidad para la entidad Player.
Seleccione Save.

Las páginas que exponen las concesiones de moneda a jugadores no están hoy en Game Manager.

API

Puede llamar a AddInventoryItems para agregar moneda a una cartera de entidad. De forma predeterminada, debe usar la autenticación de entidad en el nivel de título para agregar arbitrariamente monedas virtuales al inventario de un jugador.

AddInventoryItems se considera una llamada de administración del título y normalmente no es algo que llame directamente el cliente del juego.

Paso 3: Actualizar un artículo del catálogo

Un artículo debe tener un valor en moneda para que se pueda comprar con moneda virtual.

Game Manager

Abra Game Manager y vaya a Economy.
Seleccione la pestaña Catalog (V2) y asegúrese de que el filtro esté en los artículos Published.
Seleccione el título del artículo que creó anteriormente.
Seleccione Edit draft item.
Seleccione ➕ Add new price y establezca un Amount seleccionando el artículo de moneda que creó. Seleccione Add para terminar.
Seleccione Save and Publish.

API

Obtenga el borrador de su artículo de catálogo llamando al punto de conexión GetDraftItem. A continuación, actualice el borrador con el punto de conexión UpdateDraftItem usando:

El EntityToken (de GetEntityToken u otra llamada login de PlayFab) en el encabezado X-EntityToken
El Entity.Id de la llamada anterior en el EntityKey.Id del artículo

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

Datos:

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

Si no establece Publish en true, deberá pasarlo al estado publicado mediante PublishDraftItem. Una vez publicado un artículo, se puede buscar y está disponible públicamente. Debe usar el “itemId” devuelto en la respuesta de GetDraftItem para poder publicar.

XBOX Services

PlayFab

Inicio rápido

Inicio rápido del catálogo v2

Parte 1: Información general del catálogo

Paso 1: Obtener permisos

API

SDK de C#

Paso 2: Configurar los ajustes del catálogo

Game Manager

API

Paso 3: Publicar un artículo en el catálogo

Game Manager

API

SDK de C#

Paso 4: Realizar una búsqueda

Game Manager

API

Parte 2: Información general del inventario y las monedas virtuales

Paso 1: Crear una moneda

Game Manager

API

Paso 2: Conceder monedas

Game Manager

API

Paso 3: Actualizar un artículo del catálogo

Game Manager

API

Consulte también

​Inicio rápido del catálogo v2

​Parte 1: Información general del catálogo

​Paso 1: Obtener permisos

​API

​SDK de C#

​Paso 2: Configurar los ajustes del catálogo

​Game Manager

​API

​Paso 3: Publicar un artículo en el catálogo

​Game Manager

​API

​SDK de C#

​Paso 4: Realizar una búsqueda

​Game Manager

​API

​Parte 2: Información general del inventario y las monedas virtuales

​Paso 1: Crear una moneda

​Game Manager

​API

​Paso 2: Conceder monedas

​Game Manager

​API

​Paso 3: Actualizar un artículo del catálogo

​Game Manager

​API

​Consulte también

Inicio rápido del catálogo v2

Parte 1: Información general del catálogo

Paso 1: Obtener permisos

API

SDK de C#

Paso 2: Configurar los ajustes del catálogo

Game Manager

API

Paso 3: Publicar un artículo en el catálogo

Game Manager

API

SDK de C#

Paso 4: Realizar una búsqueda

Game Manager

API

Parte 2: Información general del inventario y las monedas virtuales

Paso 1: Crear una moneda

Game Manager

API

Paso 2: Conceder monedas

Game Manager

API

Paso 3: Actualizar un artículo del catálogo

Game Manager

API

Consulte también