ユーザー生成コンテンツにレーティングを追加する

  • [アーティクル]

Important

エコノミー v2 が一般提供になりました。 サポートとフィードバックについては、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 イベントでのみ発生します。 クエリにはゲーム マネージャー内にあるデータ エクスプローラーを使用します。 クエリの例を次に示します。

次のクエリは、過去 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 は、タイトル エンティティのみが呼び出すことができます。 この呼び出しには、取り下げられる一連のレビューが含まれています。

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

注意

要求の処理により、レビューが削除されるまでに最大で 24 時間の遅延が発生する可能性があります。

評価デザインとキャッシュ

評価を取得するメソッドは 2 つあります。 2 つのパスの違いは、レビューを直接操作しているか、カタログ アイテムを操作しているかです。

  1. 評価を直接提供します (GetItemReviews 経由、など)
  2. カタログ項目の評価集計を提供します (SearchItems 経由 など)。

どちらのルートも非同期であり、タイミング遅延があるため、その点を理解することが重要です。

直接レーティング (GetItemReviews など)

これらの評価とレビューはすべて直接提供されます。 待機時間には 2 つのカテゴリがあります。

  1. 個々のレビュー - Near Real Time
    個々のレビューはすぐには利用できませんが、数秒以内に表示されます。 新しいレビューを読むには、バックオフを使用して再試行するだけで十分なはずです。
  2. 評価の集計 - 15 分以内 に集計のキャッシュ

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

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

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