コンテンツへの評価の追加 - XBOX Game Development Documentation

Economy v2 が一般提供 (GA) されました。サポートとフィードバックについては、PlayFab フォーラムを参照してください。

このガイドでは、ゲームに評価およびレビューシステムを追加するために使用できる API 呼び出しについて説明します。

アイテムのレビュー

クライアントから ReviewItem API を呼び出すことで、アイテムに評価またはレビューを添付できます。アイテムをレビューするには、そのアイテムがすべてのプレイヤーに対して公開カタログで表示されている必要があります。評価およびレビューは API を呼び出したプレイヤーに紐付けられ、1 つのアイテムにつきプレイヤーごとに 1 件のレビューのみを関連付けることができます。アイテムの作成者は、自分自身のアイテムに対してレビューを送信することはできません。レビューは 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 を呼び出すと、値がゼロにされた 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 を使用して、1 つ以上のレビューをテイクダウンするリクエストを送信できます。この API は title entity からのみ呼び出すことができます。この呼び出しは、テイクダウンするレビューのセットを受け取ります。

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

リクエストの処理により、レビューがテイクダウンされるまで最大 24 時間の遅延が発生する可能性があります。

評価の設計とキャッシング

評価を取得する方法は 2 つあります。2 つのパスの違いは、レビューと直接やり取りするか、カタログアイテムとやり取りするかにあります。

評価を直接提供します (GetItemReviews などを介して)
評価の集計値をカタログアイテムに含めて提供します (SearchItems などを介して)

どちらの経路も非同期であり、理解しておくべきタイミングの遅延があります。

直接評価 (GetItemReviews など)

これらの評価およびレビューはすべて直接提供されます。ここには 2 つのカテゴリのレイテンシーがあります。

個別レビュー - ほぼリアルタイム
個別レビューはすぐには利用できませんが、数秒以内に表示されるはずです。バックオフを付けて再試行すれば、新しく作成されたレビューを読み取るのに十分なはずです。
集計評価 - 15 分未満 集計値にはキャッシュがあります

カタログアイテムの評価 (SearchItems など)

これらの評価はすべて、公開されたカタログのカタログアイテムの一部として提供されます。

集計評価 - 8 時間未満
システムは評価を集計し、更新をカタログにプッシュします。更新には 4 ～ 8 時間かかることがあります。

​アイテムのレビュー

​アイテムに対するプレイヤーのレビューの取得

​アイテムに対するレビューの取得

​レビューへの参考度投票の送信

​レビューの報告

​レビューのテイクダウン

​評価の設計とキャッシング

​直接評価 (GetItemReviews など)

​カタログ アイテムの評価 (SearchItems など)

アイテムのレビュー

アイテムに対するプレイヤーのレビューの取得

アイテムに対するレビューの取得

レビューへの参考度投票の送信

レビューの報告

レビューのテイクダウン

評価の設計とキャッシング

直接評価 (GetItemReviews など)

カタログアイテムの評価 (SearchItems など)