콘텐츠에 평점 추가 - XBOX Game Development Documentation

Economy v2는 이제 정식으로 사용할 수 있습니다(GA). 지원 및 피드백은 PlayFab Forum을 방문하세요.

이 가이드에서는 게임에 평점 및 리뷰 시스템을 추가하는 데 사용할 수 있는 API 호출을 살펴봅니다.

아이템 리뷰

클라이언트에서 ReviewItem API를 호출하여 아이템에 평점 또는 리뷰를 첨부할 수 있습니다. 아이템을 리뷰하려면 모든 플레이어의 공용 카탈로그에 표시되어야 합니다. 평점과 리뷰는 API를 호출하는 플레이어에게 첨부되며 플레이어당 하나의 리뷰만 아이템에 연결될 수 있습니다. 아이템 작성자는 자신의 아이템에 대해 리뷰를 제출할 수 없습니다. 리뷰는 ReviewItem이 호출될 때마다 업데이트됩니다. 호출에 필수로 필요한 데이터는 다음과 같습니다.

Id: 리뷰할 아이템의 고유 ID.
Rating: 1~5 등급 형태의 숫자 평점.

또한 선택적 매개 변수도 추가할 수 있습니다.

Title: 리뷰의 제목.
ReviewText: 리뷰용 자유 텍스트 필드.
IsInstalled: 리뷰어가 아이템을 가지고 있는지 나타내는 플래그.
ItemVersion: 리뷰되는 아이템의 버전 번호.

{
  "Review": {
    "ItemVersion": "2.4.1",
    "Rating": 5,
    "Title": "Best Game Ever",
    "ReviewText": "I play this game every day. It's my favorite game yet.",
    "IsInstalled": true
  },
  "Id": "3f5dd8d4-4ee1-4748-8855-56a8a0277bf9"
}

리뷰가 제출되면 Submitted 타임스탬프가 자동으로 채워지고 업데이트됩니다.

아이템에 대한 플레이어의 리뷰 가져오기

클라이언트에서 GetEntityItemReview API를 호출하여 아이템에 대한 플레이어의 리뷰를 가져올 수 있습니다. 아이템 Id 또는 AlternateId를 제공해야 합니다. 리뷰와 관련된 특정 ReviewId가 반환됩니다.

{
    "code": 200,
    "status": "OK",
    "data": {
        "Review": {
            "ReviewId": "730de69c-d6af-f313-4653-09fb14bedeef",
            "ItemId": "3f5dd8d4-4ee1-4748-8855-56a8a0277bf9",
            "ReviewerId": "title_player_account!218870DE55036998",
            "ItemVersion": "2.4.1",
            "Title": "Best Game Ever",
            "ReviewText": "I play this game every day. It's my favorite game yet.",
            "Rating": 5,
            "IsInstalled": true,
            "Locale": "NEUTRAL",
            "HelpfulnessVotes": 0,
            "HelpfulPositive": 0,
            "HelpfulNegative": 0,
            "Submitted": "2021-08-09T06:44:22.569Z"
        }
    }
}

리뷰를 하지 않은 플레이어에 대해 GetEntityItemReview를 호출하면 0으로 초기화된 값의 Review 개체가 반환됩니다.

{
    "code": 200,
    "status": "OK",
    "data": {
        "Review": {
            "ReviewId": "00000000-0000-0000-0000-000000000000",
            "Rating": 0,
            "IsInstalled": false,
            "HelpfulnessVotes": 0,
            "HelpfulPositive": 0,
            "HelpfulNegative": 0,
            "Submitted": "0001-01-01T00:00:00Z"
        }
    }
}

아이템에 대한 리뷰 가져오기

GetItemReviews API를 호출하여 아이템의 텍스트가 포함된 모든 리뷰에 액세스할 수 있습니다. 아이템 Id 또는 AlternateId를 제공해야 합니다. 선택적 매개 변수를 추가할 수 있습니다.

ContinuationToken: 사용 가능한 경우 다음 아이템 페이지를 검색하는 데 사용되는 불투명 토큰.
Count: 검색할 아이템 수. 최대 페이지 크기는 200. 지정되지 않으면 기본값은 10.
OrderBy: 쿼리 결과를 정렬하는 데 사용되는 OData orderBy. 가능한 값은 Helpfulness, Rating, Submitted.

{
  "Count": 2,
  "Id": "3f5dd8d4-4ee1-4748-8855-56a8a0277bf9",
  "OrderBy": "Submitted desc"
}

리뷰에 도움됨 투표 제출

플레이어는 SubmitItemReviewVote API를 호출하여 리뷰에 대한 도움됨 투표를 제출할 수 있습니다. 새 도움됨 투표를 제출하면 Vote 매개 변수의 부울 값에 따라 HelpfulPositive 또는 HelpfulNegative가 증가합니다.

{
  "ReviewId": "730de69c-d6af-f313-4653-09fb14bedeef",
  "Vote": "Helpful/UnHelpful"
}

리뷰 신고

플레이어는 클라이언트에서 ReportItemReview API를 호출하여 리뷰를 신고할 수 있습니다. ReviewId를 제공해야 합니다. 선택적 ConcernCategory 매개 변수를 추가할 수 있습니다.

{
  "ReviewId": "730de69c-d6af-f313-4653-09fb14bedeef",
  "ConcernCategory": "OffensiveContent"
}

지정되지 않으면 ConcernCategory의 기본값은 None입니다. 유효한 ConcernCategory 값은 다음과 같습니다.

None
OffensiveContent
ChildExploitation
MalwareOrVirus
PrivacyConcerns
MisleadingApp
PoorPerformance
ReviewResponse
SpamAdvertising
Profanity

ReportItemReview를 호출하면 이벤트 이름 item_reported 아래에서 PlayStream 이벤트만 발생합니다. Game Manager의 Data Explorer를 사용하여 쿼리하세요. 예제 쿼리는 아래에서 볼 수 있습니다. 다음 쿼리는 지난 3일 동안 ItemId별 ConcernCategory별 총 신고 수를 반환합니다.

['events.all']
| where Timestamp > ago (3d)
| where FullName_Name == "review_reported"
| project ReviewId = tostring(EventData.Payload.ReviewId), ConcernCategory = tostring(EventData.Payload.ConcernCategory)
| summarize TotalReportCount = count() by ReviewId, ConcernCategory
| sort by TotalReportCount desc
| render columnchart kind=stacked

리뷰 삭제

TakedownItemReviews API를 사용하여 하나 이상의 리뷰를 삭제하는 요청을 제출할 수 있습니다. 이 API는 title entity만 호출할 수 있습니다. 호출은 삭제할 리뷰 집합을 받습니다.

{
  "Reviews": [
    {
      "ItemId": "3f5dd8d4-4ee1-4748-8855-56a8a0277bf9",
      "ReviewId": "730de69c-d6af-f313-4653-09fb14bedeef"
    }
  ]
}

요청 처리로 인해 리뷰가 삭제되기까지 최대 24시간의 지연이 있을 수 있습니다.

평점 설계 및 캐싱

평점을 가져오는 두 가지 방법이 있습니다. 두 경로의 차이점은 리뷰와 직접 상호 작용하는지 카탈로그 아이템과 상호 작용하는지에 있습니다.

평점을 직접 제공(예: GetItemReviews 등)
카탈로그 아이템의 평점 집계 제공(예: SearchItems 등)

두 경로 모두 비동기적이며 이해해야 하는 시간 지연이 있습니다.

직접 평점(GetItemReviews 등)

이러한 모든 평점 및 리뷰는 직접 제공됩니다. 여기에는 두 가지 지연 시간 범주가 있습니다.

개별 리뷰 - 거의 실시간
개별 리뷰는 즉시 사용할 수 없지만 몇 초 이내에 표시되어야 합니다. 백오프를 사용하여 다시 시도하는 것으로 새로 만든 리뷰를 읽는 데 충분할 것으로 예상됩니다.
집계 평점 - 15분 미만 집계용 캐시가 있습니다.

카탈로그 아이템 평점(SearchItems 등)

이러한 모든 평점은 게시된 카탈로그의 카탈로그 아이템의 일부로 제공됩니다.

집계 평점 - 8시간 미만
시스템은 평점을 집계하고 카탈로그에 업데이트를 푸시합니다. 업데이트는 4~8시간이 걸릴 수 있습니다.

​아이템 리뷰

​아이템에 대한 플레이어의 리뷰 가져오기

​아이템에 대한 리뷰 가져오기

​리뷰에 도움됨 투표 제출

​리뷰 신고

​리뷰 삭제

​평점 설계 및 캐싱

​직접 평점(GetItemReviews 등)

​카탈로그 아이템 평점(SearchItems 등)

아이템 리뷰

아이템에 대한 플레이어의 리뷰 가져오기

아이템에 대한 리뷰 가져오기

리뷰에 도움됨 투표 제출

리뷰 신고

리뷰 삭제

평점 설계 및 캐싱

직접 평점(GetItemReviews 등)

카탈로그 아이템 평점(SearchItems 등)