Schnellstart für Katalog v2

Wichtig

Economy v2 ist jetzt allgemein verfügbar. Unterstützung und Feedback erhalten Sie im PlayFab-Forum.

Nachdem Sie sich mit Game Manager vertraut machen, können Sie:

1. Richten Sie die Berechtigungen, Einstellungen und Elemente eines v2-Katalogs ein.
2. Einrichten der Belegüberprüfung
3. Exemplarische Vorgehensweise beim Kauf eines Artikels

Eine ausführliche exemplarische Vorgehensweise in Unity finden Sie im Unity-spezifischen Tutorial .

Teil 1: Katalogübersicht

Schritt 1: Abrufen von Berechtigungen

Der erste Schritt besteht darin, den Katalog auf der Einstellungsseite in der Game Manager-Benutzeroberfläche unter ⚙️ Titeleinstellungen>Wirtschaft (V2) zu aktivieren. Sie können die UpdateCatalogConfig API verwenden und das IsCatalogEnabled Flag auf true festlegen.

Für die Interaktion mit dem Katalog müssen Sie sich entweder bei GameManger anmelden und die Websitetools verwenden oder ein Entitätstoken für die Verwendung der APIs abrufen. Die einfachste Möglichkeit zum Abrufen eines Entitätstokens ist die GetEntityToken-API .

Notiz

Um die API als Administrator oder autoritativen Dienst aufzurufen, was Sie vor dem Erstellen Ihres ersten Katalogelements tun müssen, müssen Sie einen X-SecretKey-Header mit einem geheimen Titelschlüssel einschließen. Sie können geheime Titelschlüssel auf der Game Manager-Benutzeroberfläche unter ⚙️ Titeleinstellungen>Geheime Schlüssel erstellen.

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

Tipp

Es empfiehlt sich, beim Aufrufen als Admin für einen Titel (auch ohne SessionTicket von einer Benutzeranmeldung) eine CustomTags-Eintragsprotokollierung einzubeziehen, die den Anruf vornimmt – unabhängig davon, ob Es sich um Sie, einen Server oder ein automatisiertes Skript handelt. Dies erleichtert das Nachverfolgen von Änderungen und das Identifizieren von Problemen beim Abfragen Ihrer PlayFab-Protokolle.

Schritt 2: Konfigurieren der Katalogeinstellungen

Katalogeinstellungen umfassen viele verschiedene Konfigurationen, von Inhaltstypen bis hin zu User-Generated Inhalt. Sie können sie alle über die API aktualisieren und abrufen und viele davon ganz einfach in Game Manager visualisieren.

Game Manager

1. Navigieren Sie in Game Manager zu ⚙️ Titeleinstellungen>Wirtschaft.
2. Wechseln Sie auf der Registerkarte Katalog (V2) zu Katalogeinstellungen.
3. Erstellen Sie einen Standardinhaltstyp (das Erstellen eines "Spielelement"-Typs ist ein guter Ausgangspunkt).

API

Rufen Sie die Catalog/GetCatalogConfig-Methode auf, und aktualisieren Sie dann updateCatalogConfig das Catalog ContentTypes-Array mit einem Catalog Type.

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

Beispiel: Rückgabenutzlast für einen Titel mit einigen Inhaltstypen für Catalog und 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": [...]
            },
            ...
        }
    }
}

Schritt 3: Veröffentlichen eines Elements im Katalog

GameManager

Navigieren Sie zu Economy>Catalog (V2).

Wählen Sie auf der Registerkarte Elemente die Option Neues Element aus.

Geben Sie die erforderlichen Metadaten ein– es gibt nur vier erforderliche Eigenschaften (Erstellertyp, Titel, Startdatum und Inhaltstyp). Wählen Sie Veröffentlichen aus.

Tipp

Der Creator-Typ ist standardmäßig auf "titel" festgelegt. Es kann jedoch Vorkommen geben, in denen Spieler Elemente für Ihr Spiel erstellen. In diesem Fall würden Sie "title_player_account" auswählen. Felder mit der Option JSON bearbeiten werden anhand von Metadaten wie der Lokalisierungssprache, die standardmäßig auf "neutral" festgelegt ist, festgelegt. Alle Datumsangaben sind UTC.

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

API

Erstellen Sie ein "Draft"-Katalogelement, indem Sie den CreateDraftItem-Endpunkt aufrufen:

• EntityToken (aus GetEntityToken oder einem anderen PlayFab-Aufruf login ) im X-EntityToken-Header
• Die Playfab-Titel-ID im CreatorEntity.Id des Elements

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

Daten:

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

Notiz

Das Versetzen des Elements in einen Entwurfszustand ist nicht erforderlich. Entwurf ist für den Zeitpunkt vorgesehen, in dem Sie erwarten, dass die Metadaten für einen bestimmten Zeitraum durchlaufen werden. Wir unterstützen den Parameter "publish", der bei Festlegung auf "true" das Element sofort veröffentlicht. Dies kann Ihnen je nach Muster ein gewisses Anrufvolumen sparen.

Sobald sich ein Element im Entwurf befindet, können Sie es mithilfe des PublishDraftItem-Endpunkts in den Status "Veröffentlicht" pushen (dieser Schritt wird unsichtbar in GameManager behandelt). Sobald ein Element veröffentlicht wurde, ist es durchsuchbar und öffentlich verfügbar. Sie müssen die itemId verwenden, die von der CreateDraftItem-Antwort zurückgegeben wird, um zu veröffentlichen.

Schritt 4: Durchführen einer Suche

Sobald der Publish-Aufruf erfolgreich ist, kann das Element mithilfe des zuvor veröffentlichten ItemId- und SearchItems-Endpunkts gesucht werden. Die Katalog-/Such-API führt eine Suche für den veröffentlichten Katalog mithilfe einer Reihe von Parametern aus, die für die API bereitgestellt werden, und gibt einen Satz paginierter Ergebnisse zurück.

Game Manager

Die Game Manager-Suche ist selbsterklärend und auf jeder Katalog v2-Seite vorhanden. Die Filter "Veröffentlicht" und " Entwurf " befinden sich oben. Wählen Sie das Filtersymbol (Trichter) neben der Schaltfläche Suchen aus, um die Liste der Filter anzuzeigen. Wählen Sie diese Option aus Enter ODATA filter , um einen OData-Filter hinzuzufügen.

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
}

Speichern Sie die ID, die später in dieser Schnellstartanleitung zurückgegeben wird.

Notiz

Katalog-/Suchfilter, orderBy- und Auswahlfelder verwenden OData als Abfragestandard.

Teil 2: Übersicht über Bestand und virtuelle Währungen

Inventarelemente und virtuelle Währungen sind die zwei im Spiel vorhandenen "Buckets" virtueller Güter, die PlayFab für Spielerentitäten unterstützt. Der Prozess ist:

1. Einrichten einer anfänglichen virtuellen Währung
2. Erstellen eines Elements mit kosten für virtuelle Währungen
3. Hinzufügen des Elements zum Inventar eines Spielers

Schritt 1: Erstellen einer Währung

Virtuelle Währungen sind das Fundament für die spielinterne Wirtschaft. Spielern und Charakteren können diese Währungen gewährt werden, die dann zum Kauf oder Handel von Gegenständen verwendet werden können.

Für Elemente können Kosten in einer virtuellen Währung oder in echtem Geld anfallen. Jeder Titel kann mehrere beliebige virtuelle Währungen unterstützen. Währungen bieten Ihrem Spiel die Flexibilität, jedes gewünschte Tauschmedium (z. B. Gold, Edelsteine, Herzen oder interstellare Guthaben) zu implementieren.

Game Manager

1. Öffnen Sie Game Manager, und wechseln Sie zu Economy>Catalog (V2).
2. Wählen Sie die Registerkarte Währung aus.
3. Wählen Sie Neue Währung aus, legen Sie das Startdatum und einen lesbaren Titel für den "neutralen" Schlüssel fest, und geben Sie im Feld Benutzerfreundliche ID einen eindeutigen Währungscode für diese Währung ein.
4. Wählen Sie Als Entwurf speichern aus. Die Element-ID wird als Währungscode für den Entwurf verwendet.
5. Zeigen Sie Ihre neue Währung an, indem Sie in der Währungsliste auf den Filter Entwurf klicken.
6. Bearbeiten Sie die Währung erneut, und wählen Sie Speichern und veröffentlichen aus. Die benutzerfreundliche ID wird als veröffentlichter Währungscode verwendet.

API

Erstellen Sie einen Entwurf eines Währungskatalogelements, indem Sie den CreateDraftItem-Endpunkt mit folgendem Typ aufrufen:

• Ein EntityToken mit Katalogberechtigungen
• Die Entity.Id als Element "Creator"
• Die Playfab-Titel-ID
• Das Element sollte ein Paket vom Typ "Currency" sein und einen Titel und eine Beschreibung enthalten.

Rufen Sie PublishItem mit der ItemId auf, die von CreateDraftItem zurückgegeben wird.

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

Daten:

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

Tipp

Ein Katalog/Eine Suche nach dem Typ "währung" gibt alle währungen zurück, die Sie definiert haben.

Schritt 2: Gewähren von Währungen

Game Manager

Ihr Entitätsplayer benötigt eine virtuelle Währung, um einen Kauf tätigen zu können.

1. Öffnen Sie GameManager, navigieren Sie zu Spieler, und wählen Sie Suchen aus, um die Liste der Spieler abzurufen.
2. Wählen Sie die Spieler-ID aus, der Sie die Währung gewähren möchten.
3. Wählen Sie die Registerkarte Bestand (V2) aus.
4. Filtern Sie nach "Währung" Typ , und wählen Sie Mehrere Elemente auswählen aus, um die vollständige Liste der Währungen anzuzeigen.
5. Wählen Sie die währung aus, die Sie erstellt haben, und geben Sie einen neuen Betrag für den Entity Player ein.
6. Wählen Sie Speichern aus.

Warnung

Die Seiten, auf denen Spielerwährungszuweisungen verfügbar sind, befinden sich heute nicht in GameManager. Weitere Informationen finden Sie in der Roadmap.

API

Sie können AddInventoryItems aufrufen, um einer Entity Wallet eine Währung hinzuzufügen. Standardmäßig müssen Sie die Entitätsauthentifizierung auf Titelebene verwenden, um dem Inventar eines Spielers willkürlich virtuelle Währungen hinzuzufügen.

Notiz

AddInventoryItems wird als Title-Administratoraufruf betrachtet und wird normalerweise nicht direkt vom Spielclient aufgerufen.

Schritt 3: Aktualisieren eines Katalogelements

Ein Artikel muss über einen Währungswert verfügen, damit er mit virtueller Währung käuflich erworben werden kann.

GameManager

1. Öffnen Sie Game Manager, und navigieren Sie zu Wirtschaft.
2. Wählen Sie die Registerkarte Katalog (V2) aus, und stellen Sie sicher, dass Sie nach Veröffentlichte Elemente gefiltert sind.
3. Wählen Sie den Titel des Zuvor erstellten Elements aus.
4. Wählen Sie Entwurf bearbeiten aus.
5. Wählen Sie Neuen Preis hinzufügen aus ➕ , und legen Sie einen Betrag fest, indem Sie das von Ihnen erstellte Währungselement auswählen. Wählen Sie Hinzufügen aus, um den Vorgang abzuschließen.
6. Wählen Sie Speichern und veröffentlichen aus.

API

Rufen Sie den Entwurf Ihres Katalogelements ab, indem Sie den GetDraftItem-Endpunkt aufrufen. Aktualisieren Sie dann den Entwurf mit dem UpdateDraftItem-Endpunkt mit:

• EntityToken (aus GetEntityToken oder einem anderen PlayFab-Aufruf login ) im X-EntityToken-Header
• Die Entity.Id aus dem vorherigen Aufruf im EntityKey.Id des Elements

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

Daten:

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

Wenn Sie nicht auf truefestlegenPublish, müssen Sie es mithilfe von PublishDraftItem in den veröffentlichten Zustand pushen. Sobald ein Element veröffentlicht wurde, ist es durchsuchbar und öffentlich verfügbar. Sie müssen die von der GetDraftItem-Antwort zurückgegebene "itemId" verwenden, um zu veröffentlichen.

Weitere Informationen

• Übersicht über Economy v2
• Einstellungen
• Stores