Démarrage rapide de Catalog v2

Economy v2 est désormais en disponibilité générale. Pour obtenir de l’aide et donner votre avis, rendez-vous sur le forum PlayFab.

Une fois familiarisé avec Game Manager, vous pouvez :

Configurer les autorisations, les paramètres et les articles d’un Catalog v2.
Configurer la validation des reçus
Suivre pas à pas l’achat d’un article

Consultez le tutoriel spécifique à 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 à GameManger et utiliser les outils du site, soit obtenir un jeton d’entité (Entity Token) 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 contenant 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}}\"}}"

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

Lorsque vous effectuez un appel en tant qu’administrateur d’un titre, c’est-à-dire sans SessionTicket issu d’une connexion utilisateur, il est recommandé d’inclure une entrée CustomTags indiquant qui effectue l’appel, qu’il s’agisse de vous, d’un serveur ou d’un script automatisé. Cela facilite le suivi des modifications et l’identification des problèmes lorsque vous interrogez vos journaux PlayFab.

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

Les paramètres du catalogue incluent de nombreuses configurations différentes, des types de contenu au contenu généré par l’utilisateur. Vous pouvez tous les mettre à jour et les récupérer via 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 Content Type par défaut (créer un type « Game Item » est un bon point de départ).

API

Appelez la méthode Catalog/GetCatalogConfig, puis mettez à jour avec 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 renvoyé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

GameManager

Accédez à Economy > Catalog (V2). Sous l’onglet Items, sélectionnez New Item. Renseignez 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 pour valeur par défaut « title », bien qu’il puisse arriver que des joueurs créent des articles pour votre jeu. Dans ce cas, vous sélectionneriez « title_player_account ». Les champs disposant de l’option Edit JSON sont indexés par des métadonnées telles que 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 « brouillon » en appelant le point de terminaison CreateDraftItem :

L’EntityToken (issu de GetEntityToken ou d’un autre appel login PlayFab) dans l’en-tête X-EntityToken
L’ID de titre PlayFab dans le champ 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}}"
  }
}

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

Placer l’article à l’état brouillon n’est pas obligatoire : l’état brouillon est destiné aux cas où vous prévoyez d’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 immédiatement l’article. Selon votre modèle d’utilisation, cela peut vous permettre de réduire le volume d’appels.

Une fois qu’un article est à l’état brouillon, vous pouvez le faire passer à l’état « publié » à l’aide du point de terminaison PublishDraftItem (cette étape est gérée de manière invisible dans GameManager). Une fois qu’un article est publié, il peut être recherché et est accessible publiquement. Vous devez utiliser l’ItemId renvoyé 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 précédemment publié 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 renvoie un ensemble de résultats paginés.

Game Manager

La recherche dans Game Manager est intuitive et est disponible sur chaque page de Catalog v2. Les filtres Published et Draft se trouvent en haut. Sélectionnez l’icône Filters (Funnel) à 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
}

Enregistrez l’ID renvoyé 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 joueur. 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 flexibilité d’implémenter le moyen d’échange de votre choix (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, définissez la Start date et un Title lisible pour la clé « neutral », puis, dans le champ Friendly ID, saisissez un code de monnaie unique pour cette monnaie.
Sélectionnez Save as draft. L’Item ID est utilisé comme code de monnaie brouillon.
Affichez votre nouvelle monnaie en sélectionnant le filtre Draft dans la liste des monnaies.
Modifiez à 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 brouillon en appelant le point de terminaison CreateDraftItem avec le type défini sur « currency », à l’aide des éléments suivants :

Un EntityToken disposant des autorisations sur le catalogue
L’Entity.Id en tant que « créateur » de l’article
L’ID de titre PlayFab
L’article doit être un bundle de type « Currency » et contenir un titre et une description

Appelez PublishItem avec l’ItemId renvoyé 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 » renverra 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 GameManager, accédez à Players et sélectionnez Search pour récupérer la liste des joueurs.
Sélectionnez l’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 Currency que vous avez créée et saisissez un nouveau montant pour l’entité Player.
Sélectionnez Save.

Les pages présentant les octrois de monnaie aux joueurs ne sont pas encore disponibles dans GameManager.

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 du catalogue

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

GameManager

Ouvrez Game Manager et accédez à Economy.
Sélectionnez l’onglet Catalog (V2) et assurez-vous que le filtre est défini 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 avec le point de terminaison UpdateDraftItem à l’aide des éléments suivants :

L’EntityToken (issu de GetEntityToken ou d’un autre appel login PlayFab) dans l’en-tête X-EntityToken
L’Entity.Id de l’appel précédent dans le champ 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 » renvoyé dans la réponse de GetDraftItem pour le publier.

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

Démarrage rapide

Démarrage rapide de Catalog v2

Partie 1 : Vue d’ensemble du catalogue

Étape 1 – Obtenir les autorisations

API

C# SDK

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

Game Manager

API

Étape 3 - Publier un article dans le catalogue

GameManager

API

C# SDK

É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 du catalogue

GameManager

API

Voir aussi

​Démarrage rapide de Catalog v2

​Partie 1 : Vue d’ensemble du catalogue

​Étape 1 – Obtenir les autorisations

​API

​C# SDK

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

​Game Manager

​API

​Étape 3 - Publier un article dans le catalogue

​GameManager

​API

​C# SDK

​É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 du catalogue

​GameManager

​API

​Voir aussi

Démarrage rapide de Catalog v2

Partie 1 : Vue d’ensemble du catalogue

Étape 1 – Obtenir les autorisations

API

C# SDK

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

Game Manager

API

Étape 3 - Publier un article dans le catalogue

GameManager

API

C# SDK

É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 du catalogue

GameManager

API

Voir aussi