Adicionar classificações ao seu conteúdo - XBOX Game Development Documentation

O Economy v2 agora está em disponibilidade geral. Para obter suporte e enviar comentários, acesse o Fórum do PlayFab.

Este guia apresenta as chamadas de API que podem ser usadas para adicionar um sistema de classificações e avaliações ao seu jogo.

Avaliar um item

Uma classificação ou avaliação pode ser anexada a um item chamando a API ReviewItem de um cliente. Para que um item possa ser avaliado, ele deve estar visível no catálogo público para todos os jogadores. Classificações e avaliações são anexadas ao jogador que chama a API, e apenas uma avaliação por jogador pode ser associada a um item. O criador de um item não pode enviar uma avaliação para o próprio item. A avaliação é atualizada sempre que ReviewItem é chamada. Os seguintes dados são obrigatórios para a chamada:

Id: o ID exclusivo do item a ser avaliado.
Rating: uma classificação numérica em uma escala de 1 a 5.

Além disso, parâmetros opcionais também podem ser adicionados:

Title: o título da avaliação.
ReviewText: um campo de texto livre para avaliações.
IsInstalled: um sinalizador que indica se o avaliador possui o item.
ItemVersion: o número da versão do item que está sendo avaliado.

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

Um carimbo de data/hora Submitted é preenchido e atualizado automaticamente quando uma avaliação é enviada.

Obter a avaliação de um jogador para um item

Você pode obter a avaliação de um jogador para um item chamando a API GetEntityItemReview de um cliente. Um Id ou AlternateId do item deve ser fornecido. Um ReviewId específico associado à avaliação será retornado.

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

Chamar GetEntityItemReview para um jogador que não fez uma avaliação retorna um objeto Review com valores zerados:

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

Obter avaliações de um item

Você pode acessar todas as avaliações que contêm texto de um item chamando a API GetItemReviews. Um Id ou AlternateId do item deve ser fornecido. Parâmetros opcionais podem ser adicionados:

ContinuationToken: um token opaco usado para recuperar a próxima página de itens, se houver.
Count: número de itens a serem recuperados. O tamanho máximo da página é 200. Se não for especificado, o padrão é 10.
OrderBy: um orderBy do OData usado para ordenar os resultados da consulta. Os valores possíveis são Helpfulness, Rating e Submitted.

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

Enviar um voto de utilidade para uma avaliação

Os jogadores podem enviar um voto de utilidade para uma avaliação chamando a API SubmitItemReviewVote. Enviar um novo voto de utilidade incrementará HelpfulPositive ou HelpfulNegative, dependendo do valor booliano do parâmetro Vote.

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

Denunciar uma avaliação

Os jogadores podem denunciar uma avaliação chamando a API ReportItemReview de um cliente. Um ReviewId deve ser fornecido. Um parâmetro opcional ConcernCategory pode ser adicionado.

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

Se não for especificado, ConcernCategory terá o valor padrão None. Os valores válidos de ConcernCategory são os seguintes:

None
OffensiveContent
ChildExploitation
MalwareOrVirus
PrivacyConcerns
MisleadingApp
PoorPerformance
ReviewResponse
SpamAdvertising
Profanity

Chamar ReportItemReview apenas disparará um evento do PlayStream com o nome de evento item_reported. Faça consultas usando o Data Explorer no Game Manager. Exemplos de consultas podem ser vistos abaixo: A consulta a seguir retorna o número total de denúncias por ConcernCategory por ItemId nos últimos 3 dias

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

Remover uma avaliação

Você pode enviar uma solicitação para remover uma ou mais avaliações usando a API TakedownItemReviews. Essa API só pode ser chamada pela entidade de título. A chamada recebe um conjunto de avaliações a serem removidas.

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

Pode haver um atraso de até 24 horas até que uma avaliação seja removida devido ao processamento da solicitação

Design e cache de classificações

Temos dois métodos para obter classificações. A diferença entre os dois caminhos é se você está interagindo diretamente com a avaliação ou com o item do catálogo.

Fornecemos classificações diretamente (via GetItemReviews etc.)
Fornecemos agregações de classificações nos itens do catálogo (via SearchItems etc.)

Ambas as rotas são assíncronas e têm atrasos que é importante entender.

Classificações diretas (GetItemReviews etc.)

Todas essas classificações e avaliações são fornecidas diretamente. Há duas categorias de latência aqui.

Avaliações individuais - Quase em tempo real
As avaliações individuais não estarão disponíveis imediatamente, mas devem aparecer em alguns segundos. Esperamos que repetir a tentativa com recuo seja suficiente para ler uma avaliação recém-criada.
Classificações agregadas - Menos de 15 minutos Há um cache para agregações

Classificações de itens do catálogo (SearchItems etc.)

Todas essas classificações são fornecidas como parte do item do catálogo a partir do nosso catálogo publicado.

Classificações agregadas - Menos de 8 horas
O sistema agrega as classificações e envia atualizações para o catálogo. As atualizações podem levar de 4 a 8 horas.

​Avaliar um item

​Obter a avaliação de um jogador para um item

​Obter avaliações de um item

​Enviar um voto de utilidade para uma avaliação

​Denunciar uma avaliação

​Remover uma avaliação

​Design e cache de classificações

​Classificações diretas (GetItemReviews etc.)

​Classificações de itens do catálogo (SearchItems etc.)

Avaliar um item

Obter a avaliação de um jogador para um item

Obter avaliações de um item

Enviar um voto de utilidade para uma avaliação

Denunciar uma avaliação

Remover uma avaliação

Design e cache de classificações

Classificações diretas (GetItemReviews etc.)

Classificações de itens do catálogo (SearchItems etc.)