Usando estatísticas e placares redefiníveis - XBOX Game Development Documentation

Este tutorial fornece um passo a passo completo de como configurar e gerenciar estatísticas com controle de versão, o que permite a redefinição de estatísticas e, por extensão, de placares. Vamos nos concentrar em como usar os métodos da API de administrador, com informações adicionais sobre como usar os métodos das APIs de cliente e servidor para consultar os dados, tanto da versão atual quanto das antigas. Nosso objetivo é fornecer uma análise técnica de como as estatísticas redefiníveis funcionam no PlayFab e de todas as maneiras como elas podem ser usadas nos seus jogos.

Estatísticas e placares

Primeiro, é importante observar que todas as estatísticas definidas para um jogador em um jogo no PlayFab fazem parte de um placar. Portanto, definir suas estatísticas também define seu placar. As estatísticas podem não estar necessariamente visíveis para os jogadores, mas elas existem. Você pode usá-las para obter listas de jogadores por uma pontuação que você define, seja para encontrar as maiores pontuações, as menores, aquelas centradas no jogador atual ou as da lista de amigos de um usuário. Muitas estatísticas em jogos são destinadas a ser valores vitalícios, o que significa que os jogadores atualizam continuamente suas pontuações, com as antigas permanecendo até que cada jogador supere seu próprio recorde pessoal. No entanto, para algumas experiências de jogador, é importante poder “zerar” o placar de tempos em tempos. Isso pode ser usado para incentivar um usuário a tentar ser o jogador mais bem classificado durante um determinado período ou simplesmente para remover das classificações os jogadores que não estão ativos há algum tempo. Como este tutorial discutirá, as estatísticas no PlayFab podem ser configuradas para serem redefinidas em um intervalo predeterminado. Isso é útil não apenas para os cenários descritos acima; também pode ser usado em títulos que precisam ter um placar distinto de pontuações recentes, que pode ser usado para coisas como desafios de jogo, em que você deseja permitir que um jogador envie um convite para alguém de nível de habilidade semelhante. Definir um período de redefinição significa que os jogadores retornados em uma chamada para GetLeaderboardAroundPlayer, por exemplo, são aqueles que jogaram recentemente e que têm pontuações semelhantes às do jogador local. Também é possível redefinir uma estatística como uma operação manual. Esse é um sistema prático para limpar quaisquer dados de testes de pré-lançamento ou de jogos alfa/beta. Isso também é útil no pior cenário, em que um bug foi introduzido no código do jogo, resultando em pontuações descontroladas. Em cada caso, você precisa ter a capacidade de deixar o placar limpo, para que os jogadores sintam que têm uma chance justa de entrar nele.

Redefinir estatísticas não exclui esses valores, como você verá abaixo. Na redefinição, as estatísticas no PlayFab são versionadas, tornando a nova versão a autoritativa, enquanto as versões anteriores são mantidas para análise posterior (e para que você possa recompensar os jogadores com base em suas pontuações antigas).

Configurando estatísticas redefiníveis

Os períodos de redefinição das estatísticas são configurados usando o conjunto da API de administrador ou o Game Manager. Em seguida, eles podem ser atualizados e consultados por meio do Game Manager, da API de servidor e da API de cliente (embora publicar estatísticas a partir do cliente exija que a opção allow client to post statistics esteja definida na guia Settings->API Features do jogo no Game Manager). Descreveremos o método de API para isso, embora os parâmetros definidos aqui sejam os mesmos usados no próprio Game Manager. Para configurar as estatísticas, você pode usar o método de administrador CreatePlayerStatisticDefinition e o método UpdatePlayerStatisticDefinition para fazer alterações posteriormente. Em ambos os casos, há apenas dois parâmetros:

StatisticName - O identificador de cadeia de caracteres da estatística do jogador.
VersionChangeInterval - O período que define quando as estatísticas devem ser redefinidas automaticamente.

O VersionChangeInterval é a chave desse recurso e pode ser definido como por hora, diário, semanal ou mensal. Ele também pode ser definido como nunca, caso você decida posteriormente que não deseja mais que a estatística seja redefinida regularmente. No exemplo a seguir, a chamada ao método CreatePlayerStatisticDefinition configura a estatística Headshots com uma redefinição diária, o que significa que o placar dessa estatística no jogo será redefinido todos os dias às 00:00 UTC.

public void CreatePlayerStatisticDefinition() {
    PlayFabAdminAPI.CreatePlayerStatisticDefinition(
        new CreatePlayerStatisticDefinitionRequest() {
            StatisticName = "Headshots",
            VersionChangeInterval = StatisticResetIntervalOption.Day
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

O exemplo a seguir mostra a resposta da chamada de API anterior.

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "Statistic":
        {
            "StatisticName": "Headshots",
            "CurrentVersion": 0,
            "VersionChangeInterval": "Day"
        }
    }
}

O código mostrado abaixo é um exemplo alternativo.

public void UpdatePlayerStatisticDefinition() {
    PlayFabAdminAPI.UpdatePlayerStatisticDefinition(
        new UpdatePlayerStatisticDefinitionRequest() {
            StatisticName = "Headshots",
            VersionChangeInterval = StatisticResetIntervalOption.Week
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

A chamada demonstra a definição do período de redefinição da estatística como semanal, com a seguinte resposta.

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "Statistic":
        {
            "StatisticName": "Headshots",
            "CurrentVersion": 0,
            "VersionChangeInterval": "Week"
        }
    }
}

Em cada caso, o resultado é o PlayerStatisticDefinition, contendo:

O ID de cadeia de caracteres da estatística (StatisticName).
O número de vezes que a estatística foi redefinida (CurrentVersion).
O período definido para quando a estatística será redefinida (VersionChangeInterval).

Os períodos de redefinição entram em vigor assim que são definidos; portanto, nesse caso, a segunda chamada significa que a redefinição agora está definida para 00:00 UTC de segunda-feira de manhã (meia-noite de domingo para segunda-feira, usando o fuso horário UTC), independentemente do que era antes da chamada. Os demais intervalos de redefinição também são definidos usando UTC, sendo que Month faz a redefinição ocorrer às 00:00 UTC do primeiro dia de cada mês. Para a lista completa, os períodos de redefinição são:

Never: Para de versionar a estatística com base no tempo.
Hour: Versiona a estatística no início de cada hora (XX:00 UTC).
Day: Versiona a estatística à meia-noite (00:00 UTC) todos os dias.
Week: Versiona a estatística à meia-noite (00:00 UTC) todas as segundas-feiras.
Month: Versiona a estatística à meia-noite (00:00 UTC) do primeiro dia de cada mês.

Estatísticas preexistentes

Todas as estatísticas definidas no jogo podem ter sua definição consultada, independentemente de terem sido configuradas como estatísticas redefiníveis ou não. É importante observar isso, pois as estatísticas podem ser criadas usando a chamada UpdatePlayerStatistics. Quaisquer estatísticas não criadas com um período de redefinição (VersionChangeInterval) não terão um inicialmente; portanto, uma consulta à configuração da estatística retornaria esse parâmetro definido como Never. Usando o exemplo acima, se o título também tivesse uma estatística chamada FlagsCaptured criada usando UpdatePlayerStatistics (ou criada no Game Manager diretamente em um jogador) e algumas semanas tivessem se passado, ela apareceria conforme mostrado na chamada abaixo.

public void GetPlayerStatisticDefinitions() {
    PlayFabAdminAPI.GetPlayerStatisticDefinitions(
        new GetPlayerStatisticDefinitionsRequest(),
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

Isso resultaria no seguinte.

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "Statistics": [
        {
            "StatisticName": "Headshots",
            "CurrentVersion": 2,
            "VersionChangeInterval": "Week"
        },
        {
            "StatisticName": "FlagsCaptured",
            "CurrentVersion": 0,
            "VersionChangeInterval": “Never”
        }]
    }
}

Nesse caso, a estatística chamada Headshots tem um intervalo de redefinição definido, e CurrentVersion indica que a estatística foi redefinida duas vezes. Enquanto isso, FlagsCaptured não tem um VersionChangeInterval, e é por isso também que o CurrentVersion é 0 (já que ela nunca foi versionada). Estatísticas criadas por meio de UpdatePlayerStatistics (ou do Game Manager do PlayFab) ainda podem ser definidas para ter um período de redefinição usando UpdatePlayerStatisticDefinition, conforme descrito acima. Depois disso, elas serão redefinidas nesse intervalo exatamente como se tivessem sido originalmente definidas usando CreatePlayerStatisticDefinition.

Redefinindo uma estatística manualmente

Na situação em que um bug do jogo permitiu trapaças em uma estatística, ou quando você simplesmente precisa redefinir para remover pontuações de partidas de pré-lançamento, a estatística pode ser forçada a ser redefinida no Game Manager ou por meio de uma chamada para IncrementPlayerStatisticVersion. Isso redefine imediatamente as estatísticas atuais que você especificar, limpando o placar do jogo e fornecendo uma base em branco para que novos valores sejam relatados. Para o nosso exemplo, essa chamada pode ser semelhante à mostrada abaixo.

public void IncrementPlayerStatisticVersion() {
    PlayFabAdminAPI.IncrementPlayerStatisticVersion(
        new IncrementPlayerStatisticVersionRequest() {
            StatisticName = "Headshots"
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

Isso incrementa a estatística Headshots mais uma vez, retornando informações sobre a versão que acabou de se tornar ativa.

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "StatisticVersion":
        {
            "StatisticName": "Headshots",
            "Version": 3,
            "ActivationTime": "2016-02-03T08:02:29.864Z",
            "ArchivalStatus": "NotScheduled"
        }
    }
}

Nesse caso, as informações de PlayerStatisticVersion são retornadas, contendo o ID da estatística (StatisticName), bem como seu número de versão, o momento em que ela se tornou a versão autoritativa (ActivationTime) e o ArchivalStatus (que sempre será NotScheduled para a versão atual). No entanto, para uma estatística que também tenha um VersionChangeInterval, a redefinição manual não alterará o próximo horário de redefinição agendado. Se uma estatística estiver agendada para ser redefinida diariamente e for redefinida manualmente às 23:30 UTC, ela ainda será redefinida novamente à meia-noite UTC.

Quando a redefinição ocorre

Conforme mencionado, quando o intervalo de redefinição ocorre, a estatística é versionada, de modo que uma nova versão fica imediatamente disponível, enquanto a versão antiga dessa estatística é arquivada para recuperação posterior. Depois que o intervalo de redefinição ocorre (ou uma redefinição manual é realizada) e a estatística é versionada, gravações na versão antiga serão aceitas por até dez minutos. Após esse ponto, a estatística é bloqueada, impedindo atualizações futuras. Depois de expiradas, as estatísticas entram no processo de arquivamento, para que possam ser recuperadas pelo título posteriormente. Os estágios do processo de arquivamento de uma estatística são:

NotScheduled - O arquivamento da estatística não foi iniciado (normalmente apenas para a versão da estatística ativa no momento).
Scheduled - O processo de arquivamento foi agendado, mas ainda não está em andamento.
InProgress - A estatística está sendo copiada para o arquivo.
Failed - Ocorreu uma falha inesperada (nesse caso, entre em contato com nossos Fóruns de suporte).
Complete - Esta versão da estatística foi arquivada.

Todas as versões anteriores e atuais de uma estatística podem ser consultadas usando GetPlayerStatisticVersions. Isso retorna as informações de cada versão, conforme mostrado no exemplo anterior de redefinição manual. Em outras palavras, essa chamada deve ser semelhante à apresentada abaixo.

public void GetPlayerStatisticVersions() {
    PlayFabAdminAPI.GetPlayerStatisticVersions(
        new GetPlayerStatisticVersionsRequest() {
            StatisticName = "Headshots"
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

Isso poderia resultar no retorno das seguintes informações para o nosso título de exemplo.

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "StatisticVersions": [
        {
            "StatisticName": "Headshots",
            "Version": 0,
            "ActivationTime": "2015-01-20T05:47:27.17Z",
            "DeactivationTime": "2016-01-25T00:00:00.000Z",
            "ArchivalStatus": "Complete",
            "ArchiveDownloadUrl": {{URL}}
        },
        {
            "StatisticName": "Headshots",
            "Version": 1,
            "ActivationTime": "2016-01-25T00:00:00.000Z",
            "DeactivationTime": "2016-02-01T00:00:00.000Z",
            "ArchivalStatus": "Complete",
            "ArchiveDownloadUrl": {{URL}}
        },
        {
            "StatisticName": "Headshots",
            "Version": 2,
            "ActivationTime": "2016-02-01T00:00:00.000Z",
            "DeactivationTime": "2016-02-03T08:02:29.864Z",
            "ArchivalStatus": "InProgress"
        },
        {
            "StatisticName": "Headshots",
            "Version": 3,
            "ActivationTime": "2016-02-03T08:02:29.864Z",
            "ArchivalStatus": "NotScheduled"
        }]
    }
}

Além dos valores retornados por IncrementPlayerStatisticVersion, a resposta também inclui os carimbos de data/hora de quando cada versão expirou (DeactivationTime) para as versões anteriores à atualmente ativa, e uma URL para baixar o CSV que contém o registro completo do placar antigo, depois que o processo de arquivamento for concluído (ArchiveDownloadUrl).

Lendo e gravando em versões de estatísticas

Por fim, do lado das APIs de servidor e cliente, as chamadas são muito semelhantes às que você conhece das chamadas originais de estatísticas de usuário e personagem do PlayFab. A diferença é que agora a versão faz parte da solicitação ou da resposta. Ao recuperar estatísticas, o valor da versão atual da estatística, bem como o próprio número da versão, é retornado. Os exemplos a seguir mostram a chamada para a estatística Headshots, bem como os dados retornados.

Solicitação do servidor

public void GetPlayerStatistics() {
    PlayFabServerAPI.GetPlayerStatistics(
        new GetPlayerStatisticsRequest() {
            PlayFabId= "_PlayFabId_",
            StatisticNames = new List<string>() { "Headshots" }
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

Resposta do servidor

{
    "code": 200,
    "status": "OK",
    "data":
    {
        "PlayFabId": {{PlayFabId}},
        "Statistics": [
        {
            "StatisticName": "Headshots",
            "Value": 10,
            "Version": "3"
        }]
    }
}

Solicitação do cliente

public void GetPlayerStatistics() {
    PlayFabClientAPI.GetPlayerStatistics(
        new GetPlayerStatisticsRequest() {
            StatisticNames = new List<string>() { "Headshots" }
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

Resposta do cliente

{
    "code": 200,
    "status": "OK",
    "data": {
        "Statistics": [
        {
            "StatisticName": "Headshots",
            "Value": 10,
            "Version": "3"
        }]
    }
}

Enquanto isso, a chamada Update aceita uma versão opcional, para permitir que o título controle qual versão está sendo atualizada, para os casos em que a versão possa ter sido incrementada durante o jogo.

Neste exemplo, se o título gravasse na versão anterior enquanto isso ainda fosse possível, ele estaria gravando na versão 2, conforme mostrado abaixo.

Solicitação do servidor

public void UpdatePlayerStatistics() {
    PlayFabServerAPI.UpdatePlayerStatistics(
        new UpdatePlayerStatisticsRequest() {
            PlayFabId= "_PlayFabId_",
            Statistics = new List<StatisticUpdate>() {
                new StatisticUpdate() {
                    StatisticName = "Headshots",
                    Version = 2,
                    Value = 10
                }
            }
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

Resposta do servidor

{
    "code": 200,
    "status": "OK",
    "data": {}
}

Solicitação do cliente

public void UpdatePlayerStatistics() {
    PlayFabClientAPI.UpdatePlayerStatistics(
        new UpdatePlayerStatisticsRequest() {
            Statistics = new List<StatisticUpdate>() {
                new StatisticUpdate() {
                    StatisticName = "Headshots",
                    Version = 2,
                    Value = 10
                }
            }
        },
        result => Debug.Log("Complete"),
        error => Debug.Log(error.GenerateErrorReport())
    );
}

Resposta do cliente

{
    "code": 200,
    "status": "OK",
    "data": {}
}

Mas lembre-se: embora a versão expirada possa receber gravações por até 10 minutos, qualquer tentativa de gravar nessa versão após esse tempo falhará, com uma resposta como a mostrada abaixo.

{
    "code": 400,
    "status": "BadRequest",
    "error": "StatisticVersionClosedForWrites",
    "errorCode": 1197,
    "errorMessage": "The statistic version is not current and is no longer accepting updates"
}

Recursos

Para fins de completude, esta seção fornece uma lista de todas as enumerações, classes e métodos de API descritos acima, com breves descrições.

Enumerações básicas

Interval - período em que a estatística (placar) será redefinida:
- Never
- Hour
- Day
- Week
- Month
StatisticVersionArchivalStatus - o status do processo de salvar os valores de estatística dos jogadores de uma versão em um arquivo para download:
- NotScheduled
- Scheduled
- InProgress
- Failed
- Complete

Classes básicas e seus membros

PlayerStatisticDefinition
- StatisticName (string) - O nome exclusivo da estatística.
- CurrentVersion (string) - A versão ativa atual da estatística, incrementada sempre que a estatística é redefinida.
- VersionChangeInterval (Interval) - O intervalo em que os valores da estatística de todos os jogadores são redefinidos.
PlayerStatisticVersion
- StatisticName (string) - O nome da estatística quando a versão se tornou ativa.
- Version (string) - A versão da estatística (um número hexadecimal codificado como cadeia de caracteres).
- ScheduledVersionChangeIntervalTime (DateTime) - O momento em que a versão da estatística estava agendada para se tornar ativa, com base no ResetInterval configurado.
- CreatedTime (DateTime) - O momento em que a versão da estatística se tornou ativa.
- ArchivalStatus (StatisticVersionArchivalStatus) - O status do processo de salvar os valores de estatística dos jogadores desta versão em um arquivo para download, se configurado.
- ResetInterval (Interval) - O intervalo de redefinição que fez a versão se tornar ativa, se configurado.
StatisticValue
- StatisticName (string) - O nome exclusivo da estatística.
- Value (Int32) - O valor da estatística para o jogador.
- Version (string) - Para um valor de estatística existente de um jogador, a versão da estatística quando ela foi carregada.
StatisticUpdate
- StatisticName (string) - O nome exclusivo da estatística.
- Version (string) - Para atualizações de um valor de estatística de um jogador, a versão da estatística a ser atualizada
- Value (Int32) - O valor da estatística para o jogador.

Métodos da API de administrador

CreatePlayerStatisticDefinition
- CreatePlayerStatisticDefinitionRequest
  - Name (string) - comprimento mínimo 1, comprimento máximo 128 - O nome exclusivo da estatística.
  - (VersionChangeInterval) (Interval) - O intervalo em que os valores da estatística de todos os jogadores são redefinidos (as redefinições começam no próximo limite de intervalo).
- CreatePlayerStatisticDefinitionResult
  - Statistic (PlayerStatisticDefinition) - A definição da estatística criada.
UpdatePlayerStatisticDefinition
- UpdatePlayerStatisticDefinitionRequest
  - StatisticName (string) - O nome exclusivo da estatística.
  - VersionChangeInterval (Interval) - O intervalo em que os valores da estatística de todos os jogadores são redefinidos (as redefinições começam no próximo limite de intervalo).
- UpdatePlayerStatisticDefinitionResult
  - Statistic (PlayerStatisticDefinition) - A definição da estatística criada.
GetPlayerStatisticDefinitions
- GetPlayerStatisticDefinitionsRequest (sem parâmetros).
- GetPlayerStatisticDefinitionsResult
  - Statistics (PlayerStatisticDefinition[]) - A matriz de definições para a redefinição.
GetPlayerStatisticVersions
- GetPlayerStatisticVersionsRequest
  - StatisticName (string) - O nome exclusivo da estatística.
- GetPlayerStatisticVersionsResult
  - StatisticVersions (PlayerStatisticVersion[]) - O histórico de alterações de versão da estatística (todas as versões).
IncrementPlayerStatisticVersion
- IncrementPlayerStatisticVersionRequest
  - StatisticName (string) - O nome exclusivo da estatística.
- IncrementPlayerStatisticVersionResult
  - StatisticVersion (PlayerStatisticVersion) - A versão da estatística que expirou como resultado desta operação (e seu status de arquivamento).

Métodos da API de cliente

GetPlayerStatistics
- GetPlayerStatisticsRequest
  - StatisticNames (string[]) - Matriz de estatísticas a serem retornadas, por seus nomes exclusivos.
- GetPlayerStatisticsResult
  - Statistics (StatisticValue[]) - Matriz de dados StatisticValue de todas as estatísticas solicitadas.
UpdatePlayerStatistics
- UpdatePlayerStatisticsRequest
  - Statistics (StatisticUpdate[]) - A estatística a ser atualizada, com os valores fornecidos.
- UpdatePlayerStatisticsResult (sem parâmetros).

Métodos da API de servidor

GetPlayerStatistics
- GetPlayerStatisticsRequest
  - PlayFabId (string) - O PlayFab ID do jogador cujas estatísticas estão sendo atualizadas.
  - StatisticNames (string[]) - Matriz de estatísticas a serem retornadas, por seus nomes exclusivos.
- GetPlayerStatisticsResult
  - Statistics (StatisticValue[]) - Matriz de dados StatisticValue de todas as estatísticas solicitadas.
UpdatePlayerStatistics
- UpdatePlayerStatisticsRequest
  - PlayFabId (string) - O PlayFab ID do jogador cujas estatísticas estão sendo atualizadas.
  - Statistics (StatisticUpdate[]) - A estatística a ser atualizada, com os valores fornecidos.
- UpdatePlayerStatisticsResult (sem parâmetros).

​Estatísticas e placares

​Configurando estatísticas redefiníveis

​Estatísticas preexistentes

​Redefinindo uma estatística manualmente

​Quando a redefinição ocorre

​Lendo e gravando em versões de estatísticas

​Solicitação do servidor

​Resposta do servidor

​Solicitação do cliente

​Resposta do cliente

​Solicitação do servidor

​Resposta do servidor

​Solicitação do cliente

​Resposta do cliente

​Recursos

​Enumerações básicas

​Classes básicas e seus membros

​Métodos da API de administrador

​Métodos da API de cliente

​Métodos da API de servidor

Estatísticas e placares

Configurando estatísticas redefiníveis

Estatísticas preexistentes

Redefinindo uma estatística manualmente

Quando a redefinição ocorre

Lendo e gravando em versões de estatísticas

Solicitação do servidor

Resposta do servidor

Solicitação do cliente

Resposta do cliente

Solicitação do servidor

Resposta do servidor

Solicitação do cliente

Resposta do cliente

Recursos

Enumerações básicas

Classes básicas e seus membros

Métodos da API de administrador

Métodos da API de cliente

Métodos da API de servidor