Démarrage rapide du catalogue v2

Economy v2 est maintenant en disponibilité générale. Pour obtenir du soutien et transmettre vos commentaires, rendez-vous sur le forum PlayFab.

Une fois que vous serez familiarisé avec Game Manager, vous pourrez :

Configurer les autorisations, les paramètres et les articles d’un catalogue v2.
Configurer la validation des reçus
Parcourir l’achat d’un article

Consultez le tutoriel propre à Unity pour une procédure détaillée dans Unity.

Partie 1 : Vue d’ensemble du catalogue

Étape 1 – Obtenir les autorisations

La première étape consiste à activer le catalogue dans la page des paramètres de l’interface utilisateur de Game Manager, sous ⚙️ Title Settings > Economy (V2). Vous pouvez utiliser l’API UpdateCatalogConfig et définir l’indicateur IsCatalogEnabled sur true. Pour interagir avec le catalogue, vous devez soit vous connecter à Game Manager et utiliser les outils du site, soit obtenir un jeton d’entité pour utiliser les API. Le moyen le plus simple d’obtenir un jeton d’entité est d’utiliser l’API GetEntityToken.

Pour appeler l’API en tant qu’administrateur ou service faisant autorité, ce que vous devrez faire avant de créer votre premier article de catalogue, vous devrez inclure un en-tête X-SecretKey avec une clé secrète de titre. Vous pouvez créer des clés secrètes de titre dans l’interface utilisateur de Game Manager, sous ⚙️ 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 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,
    };
}

Lorsque vous effectuez un appel en tant qu’administrateur d’un titre, c’est-à-dire sans SessionTicket provenant de la connexion d’un utilisateur, il est recommandé d’inclure une entrée CustomTags indiquant qui effectue l’appel, que ce soit vous, un serveur ou un script automatisé. Il est ainsi plus facile de suivre les modifications et de cerner les problèmes lorsque vous interrogez vos journaux PlayFab.

Étape 2 - Configurer les paramètres de votre catalogue

Les paramètres du catalogue comprennent de nombreuses configurations différentes, des types de contenu au contenu généré par les utilisateurs. Vous pouvez tous les mettre à jour et les récupérer au moyen de l’API, et en visualiser facilement un grand nombre dans Game Manager.

Game Manager

Dans Game Manager, accédez à ⚙️ Title Settings > Economy.
Sous l’onglet Catalog (V2), accédez à Catalog Settings
Créez un type de contenu par défaut (la création d’un type « Game Item » est un bon point de départ).

API

Appelez la méthode Catalog/GetCatalogConfig, puis mettez à jour, à l’aide de UpdateCatalogConfig, le tableau ContentTypes du catalogue avec un type de catalogue.

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

Exemple de charge utile retournée pour un titre comportant quelques types de contenu pour le catalogue et l’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": [...]
            },
            ...
        }
    }
}

Étape 3 - Publier un article dans le catalogue

Game Manager

Accédez à Economy > Catalog (V2). Sous l’onglet Items, sélectionnez New Item. Remplissez les métadonnées requises; seules quatre propriétés sont obligatoires (Creator Type, Title, Start date et Content type). Sélectionnez Publish.

Creator Type a la valeur par défaut « title », mais il peut arriver que des joueurs créent des articles pour votre jeu. Dans ce cas, vous sélectionneriez « title_player_account ». Les champs offrant l’option Edit JSON sont indexés par des métadonnées comme la langue de localisation, dont la valeur par défaut est « neutral ». Toutes les dates sont en UTC.

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

API

Créez un article de catalogue à l’état « Draft » (brouillon) en appelant le point de terminaison CreateDraftItem avec :

L’EntityToken (provenant de GetEntityToken ou d’un autre appel login de PlayFab) dans l’en-tête X-EntityToken
L’ID de titre PlayFab dans le CreatorEntity.Id de l’article

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

Données :

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

Il n’est pas obligatoire de placer l’article à l’état de brouillon (Draft); cet état est prévu lorsque vous comptez itérer sur les métadonnées pendant un certain temps. Nous prenons en charge le paramètre « publish » qui, lorsqu’il est défini sur « true », publie l’article immédiatement. Selon votre modèle d’utilisation, cela pourrait vous permettre de réduire le volume d’appels.

Une fois qu’un article est à l’état de brouillon, vous pouvez le faire passer à l’état « Published » à l’aide du point de terminaison PublishDraftItem (cette étape est gérée de façon transparente dans Game Manager). Une fois qu’un article est publié, il peut être recherché et est accessible publiquement. Vous devez utiliser l’ItemId retourné dans la réponse de CreateDraftItem pour le publier.

Étape 4 - Effectuer une recherche

Une fois l’appel de publication réussi, l’article peut être recherché à l’aide de l’ItemId publié précédemment et du point de terminaison SearchItems. L’API Catalog/Search exécute une recherche dans le catalogue publié à l’aide d’un ensemble de paramètres fournis à l’API et retourne un ensemble de résultats paginés.

Game Manager

La recherche dans Game Manager est intuitive et se trouve sur chaque page du catalogue v2. Les filtres Published et Draft se trouvent en haut. Sélectionnez l’icône Filters (entonnoir) à côté du bouton Search pour afficher la liste des filtres. Sélectionnez Enter ODATA filter pour ajouter un filtre 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
}

Conservez l’ID retourné pour la suite de ce démarrage rapide.

Les champs filter, orderBy et select de Catalog/Search utilisent OData comme norme de requête.

Partie 2 : Vue d’ensemble de l’inventaire et des monnaies virtuelles

Les articles d’inventaire et les monnaies virtuelles sont les deux « compartiments » de biens virtuels en jeu que PlayFab prend en charge pour les entités de joueurs. Le processus est le suivant :

Configurer une monnaie virtuelle initiale
Créer un article avec un coût en monnaie virtuelle
Ajouter l’article à l’inventaire d’un joueur

Étape 1 : Créer une monnaie

Les monnaies virtuelles sont le fondement des économies en jeu. Ces monnaies peuvent être accordées aux joueurs et aux personnages, qui peuvent ensuite les utiliser pour acheter ou échanger des articles. Les articles peuvent avoir un coût en monnaie virtuelle ou en argent réel. Chaque titre peut prendre en charge plusieurs monnaies virtuelles arbitraires. Les monnaies offrent à votre jeu la souplesse nécessaire pour mettre en œuvre le moyen d’échange que vous souhaitez (par exemple, de l’or, des gemmes, des cœurs ou des crédits interstellaires).

Game Manager

Ouvrez Game Manager et accédez à Economy > Catalog (V2).
Sélectionnez l’onglet Currency.
Choisissez New Currency, puis définissez la Start date, un Title lisible pour la clé « neutral » et, dans le champ Friendly ID, entrez un code de monnaie unique pour cette monnaie.
Sélectionnez Save as draft. L’Item ID est utilisé comme code de monnaie à l’état de brouillon.
Affichez votre nouvelle monnaie en sélectionnant le filtre Draft dans la liste des monnaies.
Modifiez de nouveau la monnaie et sélectionnez Save and publish. Le Friendly ID est utilisé comme code de monnaie publiée.

API

Créez un article de catalogue de monnaie à l’état de brouillon en appelant le point de terminaison CreateDraftItem avec le type défini sur « currency », en utilisant :

Un EntityToken disposant d’autorisations sur le catalogue
L’Entity.Id comme « Creator » de l’article
L’ID de titre PlayFab
L’article doit être un ensemble (Bundle) de type « Currency » et contenir un titre et une description

Appelez PublishItem avec l’ItemId retourné par CreateDraftItem.

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

Données :

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

Une recherche Catalog/Search sur le type « currency » retournera toutes les monnaies que vous avez définies.

Étape 2 - Accorder des monnaies

Game Manager

Votre entité joueur a besoin de monnaie virtuelle pour effectuer un achat.

Ouvrez Game Manager, accédez à Players et sélectionnez Search pour récupérer la liste des joueurs.
Sélectionnez le Player ID du joueur auquel vous souhaitez accorder de la monnaie.
Sélectionnez l’onglet Inventory (V2).
Filtrez sur le Type « Currency » et sélectionnez Pick multiple items pour afficher la liste complète des monnaies.
Choisissez la monnaie que vous avez créée et entrez un nouveau montant pour l’entité Player.
Sélectionnez Save.

Les pages présentant les attributions de monnaie aux joueurs ne figurent pas dans Game Manager actuellement.

API

Vous pouvez appeler AddInventoryItems pour ajouter de la monnaie au portefeuille d’une entité. Par défaut, vous devez utiliser l’authentification d’entité au niveau du titre pour ajouter arbitrairement des monnaies virtuelles à l’inventaire d’un joueur.

AddInventoryItems est considéré comme un appel d’administration du titre et n’est normalement pas appelé directement par le client du jeu.

Étape 3 - Mettre à jour un article de catalogue

Un article doit avoir une valeur en monnaie pour pouvoir être acheté avec de la monnaie virtuelle.

Game Manager

Ouvrez Game Manager et accédez à Economy.
Sélectionnez l’onglet Catalog (V2) et assurez-vous que le filtre est réglé sur les articles Published.
Sélectionnez le titre de l’article que vous avez créé précédemment.
Sélectionnez Edit draft item.
Sélectionnez ➕ Add new price et définissez un Amount en sélectionnant l’article de monnaie que vous avez créé. Sélectionnez Add pour terminer.
Sélectionnez Save and Publish.

API

Obtenez le brouillon de votre article de catalogue en appelant le point de terminaison GetDraftItem. Mettez ensuite à jour le brouillon à l’aide du point de terminaison UpdateDraftItem avec :

L’EntityToken (provenant de GetEntityToken ou d’un autre appel login de PlayFab) dans l’en-tête X-EntityToken
L’Entity.Id de l’appel précédent dans l’EntityKey.Id de l’article

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

Données :

{
  "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 vous ne définissez pas Publish sur true, vous devez faire passer l’article à l’état publié à l’aide de PublishDraftItem. Une fois qu’un article est publié, il peut être recherché et est accessible publiquement. Vous devez utiliser l’« itemId » retourné dans la réponse de GetDraftItem pour le publier.

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

Démarrage rapide

Démarrage rapide du catalogue v2

Partie 1 : Vue d’ensemble du catalogue

Étape 1 – Obtenir les autorisations

API

SDK C#

Étape 2 - Configurer les paramètres de votre catalogue

Game Manager

API

Étape 3 - Publier un article dans le catalogue

Game Manager

API

SDK C#

Étape 4 - Effectuer une recherche

Game Manager

API

Partie 2 : Vue d’ensemble de l’inventaire et des monnaies virtuelles

Étape 1 : Créer une monnaie

Game Manager

API

Étape 2 - Accorder des monnaies

Game Manager

API

Étape 3 - Mettre à jour un article de catalogue

Game Manager

API

Voir aussi

​Démarrage rapide du catalogue v2

​Partie 1 : Vue d’ensemble du catalogue

​Étape 1 – Obtenir les autorisations

​API

​SDK C#

​Étape 2 - Configurer les paramètres de votre catalogue

​Game Manager

​API

​Étape 3 - Publier un article dans le catalogue

​Game Manager

​API

​SDK C#

​Étape 4 - Effectuer une recherche

​Game Manager

​API

​Partie 2 : Vue d’ensemble de l’inventaire et des monnaies virtuelles

​Étape 1 : Créer une monnaie

​Game Manager

​API

​Étape 2 - Accorder des monnaies

​Game Manager

​API

​Étape 3 - Mettre à jour un article de catalogue

​Game Manager

​API

​Voir aussi

Démarrage rapide du catalogue v2

Partie 1 : Vue d’ensemble du catalogue

Étape 1 – Obtenir les autorisations

API

SDK C#

Étape 2 - Configurer les paramètres de votre catalogue

Game Manager

API

Étape 3 - Publier un article dans le catalogue

Game Manager

API

SDK C#

Étape 4 - Effectuer une recherche

Game Manager

API

Partie 2 : Vue d’ensemble de l’inventaire et des monnaies virtuelles

Étape 1 : Créer une monnaie

Game Manager

API

Étape 2 - Accorder des monnaies

Game Manager

API

Étape 3 - Mettre à jour un article de catalogue

Game Manager

API

Voir aussi