Adición de valoraciones a su contenido - XBOX Game Development Documentation

Economy v2 ya está disponible con carácter general. Para obtener soporte técnico y enviar comentarios, vaya al foro de PlayFab.

Esta guía repasa las llamadas a la API que se pueden usar para agregar un sistema de valoraciones y reseñas a su juego.

Reseñar un artículo

Se puede adjuntar una valoración o reseña a un artículo llamando a la API ReviewItem desde un cliente. Para que un artículo pueda reseñarse, debe estar visible en el catálogo público para todos los jugadores. Las valoraciones y reseñas se adjuntan al jugador que llama a la API, y solo se puede asociar una única reseña por jugador a un artículo. El creador de un artículo no puede enviar una reseña de su propio artículo. La reseña se actualiza cada vez que se llama a ReviewItem. Los siguientes datos son obligatorios para la llamada:

Id: el identificador único del artículo que se va a reseñar.
Rating: una valoración numérica en una escala de 1 a 5.

Además, también se pueden agregar parámetros opcionales:

Title: el título de la reseña.
ReviewText: un campo de texto libre para las reseñas.
IsInstalled: una marca para indicar si el autor de la reseña tiene el artículo.
ItemVersion: el número de versión del artículo que se está reseñando.

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

Una marca de tiempo Submitted se rellena y actualiza automáticamente cuando se envía una reseña.

Obtener la reseña de un jugador para un artículo

Puede obtener la reseña de un jugador para un artículo llamando a la API GetEntityItemReview desde un cliente. Se debe proporcionar un Id o AlternateId del artículo. Se devolverá un ReviewId específico asociado a la reseña.

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

Llamar a GetEntityItemReview desde un jugador que no ha hecho ninguna reseña devuelve un objeto Review con valores a cero:

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

Obtener las reseñas de un artículo

Puede acceder a todas las reseñas que contienen texto de un artículo llamando a la API GetItemReviews. Se debe proporcionar un Id o AlternateId del artículo. Se pueden agregar parámetros opcionales:

ContinuationToken: un token opaco usado para recuperar la siguiente página de artículos, si hay alguna disponible.
Count: número de artículos que se recuperarán. El tamaño máximo de página es 200. Si no se especifica, el valor predeterminado es 10.
OrderBy: una cláusula orderBy de OData usada para ordenar los resultados de la consulta. Los valores posibles son Helpfulness, Rating y Submitted.

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

Enviar un voto de utilidad para una reseña

Los jugadores pueden enviar un voto de utilidad para una reseña llamando a la API SubmitItemReviewVote. Enviar un nuevo voto de utilidad incrementará HelpfulPositive o HelpfulNegative según el valor booleano del parámetro Vote.

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

Denunciar una reseña

Los jugadores pueden denunciar una reseña llamando a la API ReportItemReview desde un cliente. Se debe proporcionar un ReviewId. Se puede agregar un parámetro opcional ConcernCategory.

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

Si no se especifica, ConcernCategory tendrá el valor predeterminado None. Los valores válidos de ConcernCategory son los siguientes:

None
OffensiveContent
ChildExploitation
MalwareOrVirus
PrivacyConcerns
MisleadingApp
PoorPerformance
ReviewResponse
SpamAdvertising
Profanity

Llamar a ReportItemReview solo desencadenará un evento de PlayStream con el nombre de evento item_reported. Realice la consulta con el Data Explorer en Game Manager. A continuación se pueden ver consultas de ejemplo: La siguiente consulta devuelve el número total de denuncias por ConcernCategory por cada ItemId en los últimos 3 días

['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

Retirar una reseña

Puede enviar una solicitud para retirar una o varias reseñas mediante la API TakedownItemReviews. Esta API solo puede ser llamada por la entidad de título. La llamada recibe un conjunto de reseñas que se van a retirar.

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

Puede haber un retraso de hasta 24 horas hasta que se retire una reseña debido al procesamiento de la solicitud

Diseño de valoraciones y almacenamiento en caché

Tenemos dos métodos para obtener valoraciones. La diferencia entre las dos rutas es si interactúa directamente con la reseña o con el artículo del catálogo.

Proporcionamos valoraciones directamente (mediante GetItemReviews, etc.)
Proporcionamos agregados de valoraciones en los artículos del catálogo (mediante SearchItems, etc.)

Ambas rutas son asincrónicas y tienen retrasos de tiempo que es importante comprender.

Valoraciones directas (GetItemReviews, etc.)

Todas estas valoraciones y reseñas se sirven directamente. Aquí hay dos categorías de latencia.

Reseñas individuales: casi en tiempo real
Las reseñas individuales no estarán disponibles de inmediato, pero deberían aparecer en unos segundos. Esperamos que reintentar con un retroceso sea suficiente para leer una reseña recién creada.
Valoraciones agregadas: menos de 15 minutos Hay una caché para los agregados

Valoraciones de los artículos del catálogo (SearchItems, etc.)

Todas estas valoraciones se sirven como parte del artículo del catálogo desde nuestro catálogo publicado.

Valoraciones agregadas: menos de 8 horas
El sistema agrega las valoraciones e inserta las actualizaciones en el catálogo. Las actualizaciones pueden tardar de 4 a 8 horas.

​Reseñar un artículo

​Obtener la reseña de un jugador para un artículo

​Obtener las reseñas de un artículo

​Enviar un voto de utilidad para una reseña

​Denunciar una reseña

​Retirar una reseña

​Diseño de valoraciones y almacenamiento en caché

​Valoraciones directas (GetItemReviews, etc.)

​Valoraciones de los artículos del catálogo (SearchItems, etc.)

Reseñar un artículo

Obtener la reseña de un jugador para un artículo

Obtener las reseñas de un artículo

Enviar un voto de utilidad para una reseña

Denunciar una reseña

Retirar una reseña

Diseño de valoraciones y almacenamiento en caché

Valoraciones directas (GetItemReviews, etc.)

Valoraciones de los artículos del catálogo (SearchItems, etc.)