Catalog v2 빠른 시작

Economy v2는 이제 정식 출시(GA)되었습니다. 지원 및 피드백은 PlayFab 포럼을 참조하세요.

Game Manager에 익숙해진 후 다음을 수행할 수 있습니다.

v2 Catalog의 권한, 설정, 아이템 설정.
영수증 유효성 검사 설정
아이템 구매 과정 살펴보기

Unity에서의 자세한 안내는 Unity 관련 튜토리얼을 참조하세요.

1부: 카탈로그 개요

1단계 – 권한 얻기

첫 번째 단계는 Game Manager UI의 ⚙️ Title Settings > **Economy (V2)**의 설정 페이지에서 카탈로그를 활성화하는 것입니다. UpdateCatalogConfig API를 사용하고 IsCatalogEnabled 플래그를 true로 설정할 수 있습니다. 카탈로그와 상호 작용하려면 Game Manager에 로그인하여 사이트 도구를 사용하거나 API 사용을 위한 엔터티 토큰을 얻어야 합니다. 엔터티 토큰을 얻는 가장 쉬운 방법은 GetEntityToken API를 사용하는 것입니다.

첫 번째 카탈로그 아이템을 생성하기 전에 관리자 또는 권한 있는 서비스로 API를 호출하려면 타이틀 시크릿 키가 포함된 X-SecretKey 헤더를 포함해야 합니다. Game Manager UI의 ⚙️ 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,
    };
}

타이틀 관리자로 호출할 때, 즉 사용자 로그인에서 오는 SessionTicket 없이 호출할 때는 누가 호출하는지(여러분, 서버 또는 자동화된 스크립트인지)를 로깅하는 CustomTags 항목을 포함하는 것이 모범 사례입니다. 이렇게 하면 PlayFab 로그를 쿼리할 때 변경 사항을 추적하고 문제를 식별하기가 더 쉽습니다.

2단계 - 카탈로그 설정 구성

카탈로그 설정에는 콘텐츠 유형부터 사용자 생성 콘텐츠에 이르기까지 여러 다양한 구성이 포함됩니다. API를 통해 모두 업데이트하고 검색할 수 있으며, 많은 항목을 Game Manager에서 쉽게 시각화할 수 있습니다.

Game Manager

Game Manager에서 ⚙️ Title Settings > Economy로 이동합니다.
Catalog (V2) 탭 아래에서 Catalog Settings로 이동합니다.
기본 _Content Type_을 만듭니다(“Game Item” 유형을 만드는 것부터 시작하는 것이 좋습니다).

API

Catalog/GetCatalogConfig 메서드를 호출한 다음 UpdateCatalogConfig로 Catalog Type이 포함된 Catalog ContentTypes 배열을 업데이트합니다.

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

Catalog와 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": [...]
            },
            ...
        }
    }
}

3단계 - 카탈로그에 아이템 게시

GameManager

Economy > **Catalog (V2)**로 이동합니다. Items 탭 아래에서 New Item을 선택합니다. 필요한 메타데이터를 입력합니다. 필수 속성은 4개뿐입니다(Creator Type, Title, Start date, Content type). Publish를 선택합니다.

Creator Type의 기본값은 “title”이지만, 플레이어가 게임용 아이템을 만드는 경우가 있을 수 있습니다. 이 경우 “title_player_account”를 선택합니다. Edit JSON 옵션이 있는 필드는 기본값이 “neutral”인 현지화 언어와 같은 메타데이터로 키가 지정됩니다. 모든 날짜는 UTC입니다.

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

API

CreateDraftItem 엔드포인트를 호출하여 “Draft” 카탈로그 아이템을 만듭니다.

X-EntityToken 헤더에 EntityToken(GetEntityToken 또는 기타 PlayFab login 호출로부터의)
아이템의 CreatorEntity.Id에 PlayFab Title ID

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

데이터:

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

아이템을 Draft 상태로 두는 것은 필수가 아닙니다. Draft는 일정 기간 동안 메타데이터를 반복적으로 업데이트할 것으로 예상될 때를 위한 것입니다. “publish” 매개 변수를 지원하며, “true”로 설정하면 아이템이 즉시 게시됩니다. 이는 사용자의 패턴에 따라 호출 볼륨을 절약할 수 있습니다.

아이템이 Draft 상태가 되면 PublishDraftItem 엔드포인트를 사용하여 ‘Published’ 상태로 전환할 수 있습니다(이 단계는 Game Manager에서 보이지 않게 처리됩니다). 아이템이 게시되면 검색할 수 있고 공개적으로 사용할 수 있습니다. 게시하려면 CreateDraftItem 응답에서 반환된 ItemId를 사용해야 합니다.

4단계 - 검색 수행

Publish 호출이 성공하면 이전에 게시된 ItemId와 SearchItems 엔드포인트를 사용하여 아이템을 검색할 수 있습니다. Catalog/Search API는 API에 제공된 매개 변수 집합을 사용하여 게시된 카탈로그에 대해 검색을 실행하고 페이징된 결과 집합을 반환합니다.

Game Manager

Game Manager 검색은 자체 설명적이며 각 Catalog v2 페이지에 존재합니다. Published 및 Draft 필터가 상단에 있습니다. Search 버튼 옆의 Filters (Funnel) 아이콘을 선택하여 필터 목록을 확인합니다. OData 필터를 추가하려면 Enter ODATA filter를 선택합니다.

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
}

이 빠른 시작에서 나중에 사용할 수 있도록 반환된 ID를 저장합니다.

Catalog/search의 filter, orderBy, select 필드는 OData를 쿼리 표준으로 사용합니다.

2부: 인벤토리 및 가상 화폐 개요

인벤토리 아이템과 가상 화폐는 PlayFab이 플레이어 엔터티를 위해 지원하는 게임 내 가상 상품의 두 가지 ‘버킷’입니다. 프로세스는 다음과 같습니다.

초기 가상 화폐 설정
가상 화폐 비용이 있는 아이템 만들기
플레이어 인벤토리에 아이템 추가

1단계: 화폐 만들기

가상 화폐는 게임 내 경제의 기반입니다. 플레이어와 캐릭터에게 이러한 화폐를 부여할 수 있으며, 이를 사용하여 아이템을 사거나 거래할 수 있습니다. 아이템은 가상 화폐 또는 실제 통화로 비용을 지정할 수 있습니다. 각 타이틀은 여러 임의의 가상 화폐를 지원할 수 있습니다. 화폐는 게임에서 원하는 교환 매체를 구현할 수 있는 유연성을 제공합니다(예: 금, 보석, 하트, 은하 크레딧).

Game Manager

Game Manager를 열고 Economy > **Catalog (V2)**로 이동합니다.
Currency 탭을 선택합니다.
New Currency를 선택하고 Start date, “neutral” 키에 대한 사람이 읽을 수 있는 _Title_을 설정하며, Friendly ID 필드에 이 화폐에 대한 고유한 통화 코드를 입력합니다.
Save as draft를 선택합니다. Item ID는 초안 통화 코드로 사용됩니다.
통화 목록에서 Draft 필터를 선택하여 새 화폐를 확인합니다.
화폐를 다시 편집하고 Save and publish를 선택합니다. Friendly ID는 게시된 통화 코드로 사용됩니다.

API

CreateDraftItem 엔드포인트를 유형이 “currency”로 설정된 상태로 호출하여 초안 통화 카탈로그 아이템을 만듭니다.

카탈로그 권한이 있는 EntityToken
아이템 ‘Creator’로 Entity.Id
PlayFab Title ID
아이템은 ‘Currency’ 유형의 번들이어야 하며 Title과 Description을 포함해야 합니다.

CreateDraftItem에서 반환된 ItemId로 PublishItem을 호출합니다.

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

데이터:

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

‘currency’ 유형에 대한 Catalog/Search는 정의된 모든 통화를 반환합니다.

2단계 - 통화 부여

Game Manager

엔터티 플레이어가 구매하려면 가상 화폐가 필요합니다.

GameManager를 열고 Players로 이동한 다음 Search를 선택하여 플레이어 목록을 검색합니다.
통화를 부여하려는 플레이어 ID를 선택합니다.
Inventory (V2) 탭을 선택합니다.
“Currency” Type으로 필터링하고 Pick multiple items를 선택하여 전체 통화 목록을 확인합니다.
만든 _Currency_를 선택하고 엔터티 _Player_에 대한 새 금액을 입력합니다.
Save를 선택합니다.

플레이어 통화 부여를 노출하는 페이지는 현재 GameManager에 없습니다.

API

AddInventoryItems를 호출하여 엔터티 지갑에 통화를 추가할 수 있습니다. 기본적으로 플레이어 인벤토리에 임의로 가상 화폐를 추가하려면 타이틀 수준 엔터티 인증을 사용해야 합니다.

_AddInventoryItems_는 타이틀 관리자 호출로 간주되며, 일반적으로 게임 클라이언트에서 직접 호출되지 않습니다.

3단계 - 카탈로그 아이템 업데이트

아이템이 가상 화폐로 구매 가능하려면 통화 값이 있어야 합니다.

GameManager

Game Manager를 열고 Economy로 이동합니다.
Catalog (V2) 탭을 선택하고 Published 아이템으로 필터링되어 있는지 확인합니다.
이전에 만든 아이템의 제목을 선택합니다.
Edit draft item을 선택합니다.
➕ Add new price를 선택하고 만든 통화 아이템을 선택하여 _Amount_를 설정합니다. Add를 선택하여 완료합니다.
Save and Publish를 선택합니다.

API

GetDraftItem 엔드포인트를 호출하여 카탈로그 아이템의 초안을 가져옵니다. 그런 다음 UpdateDraftItem 엔드포인트를 사용하여 초안을 업데이트합니다.

X-EntityToken 헤더에 EntityToken(GetEntityToken 또는 기타 PlayFab login 호출로부터의)
아이템의 EntityKey.Id에 이전 호출의 Entity.Id

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

데이터:

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

Publish를 true로 설정하지 않은 경우 PublishDraftItem을 사용하여 게시된 상태로 전환해야 합니다. 아이템이 게시되면 검색할 수 있고 공개적으로 사용할 수 있습니다. 게시하려면 GetDraftItem 응답에서 반환된 “itemId”를 사용해야 합니다.

XBOX Services

PlayFab

빠른 시작

Catalog v2 빠른 시작

1부: 카탈로그 개요

1단계 – 권한 얻기

API

C# SDK

2단계 - 카탈로그 설정 구성

Game Manager

API

3단계 - 카탈로그에 아이템 게시

GameManager

API

C# SDK

4단계 - 검색 수행

Game Manager

API

2부: 인벤토리 및 가상 화폐 개요

1단계: 화폐 만들기

Game Manager

API

2단계 - 통화 부여

Game Manager

API

3단계 - 카탈로그 아이템 업데이트

GameManager

API

참고 항목

​Catalog v2 빠른 시작

​1부: 카탈로그 개요

​1단계 – 권한 얻기

​API

​C# SDK

​2단계 - 카탈로그 설정 구성

​Game Manager

​API

​3단계 - 카탈로그에 아이템 게시

​GameManager

​API

​C# SDK

​4단계 - 검색 수행

​Game Manager

​API

​2부: 인벤토리 및 가상 화폐 개요

​1단계: 화폐 만들기

​Game Manager

​API

​2단계 - 통화 부여

​Game Manager

​API

​3단계 - 카탈로그 아이템 업데이트

​GameManager

​API

​참고 항목

Catalog v2 빠른 시작

1부: 카탈로그 개요

1단계 – 권한 얻기

API

C# SDK

2단계 - 카탈로그 설정 구성

Game Manager

API

3단계 - 카탈로그에 아이템 게시

GameManager

API

C# SDK

4단계 - 검색 수행

Game Manager

API

2부: 인벤토리 및 가상 화폐 개요

1단계: 화폐 만들기

Game Manager

API

2단계 - 통화 부여

Game Manager

API

3단계 - 카탈로그 아이템 업데이트

GameManager

API

참고 항목