Uso de estadísticas y tablas de clasificación restablecibles

Este tutorial proporciona un tutorial completo sobre cómo configurar y administrar estadísticas con control de versiones, lo que permite restablecer las estadísticas y, por extensión, las tablas de clasificación. Nos centraremos en cómo usar los métodos de la API de administración, con información adicional sobre cómo usar los métodos de las API de cliente y servidor para consultar los datos, tanto de la versión actual como de las antiguas. Nuestro objetivo es proporcionarle una revisión técnica de cómo funcionan las estadísticas restablecibles en PlayFab y todas las formas en que se pueden usar en sus juegos.

Estadísticas y tablas de clasificación

En primer lugar, es importante tener en cuenta que todas las estadísticas definidas para un jugador en un juego de PlayFab forman parte de una tabla de clasificación. Por tanto, definir sus estadísticas define también su tabla de clasificación. Puede que las estadísticas no sean necesariamente visibles para los jugadores, pero están ahí. Puede usarlas para obtener listas de jugadores según una puntuación que usted defina, ya sea para encontrar las puntuaciones más altas, las más bajas, las centradas en el jugador actual o las de la lista de amigos de un usuario. Muchas estadísticas de los juegos están pensadas como valores de por vida, lo que significa que los jugadores actualizan continuamente sus puntuaciones y las antiguas se mantienen hasta que cada jugador supera su propio récord personal. Sin embargo, para algunas experiencias de jugador, es importante poder “borrar” la tabla de clasificación de vez en cuando. Esto puede usarse para animar a un usuario a intentar ser el jugador mejor clasificado durante un período determinado, o simplemente para eliminar de las clasificaciones a los jugadores que no han estado activos durante un tiempo. Como se explica en este tutorial, las estadísticas de PlayFab se pueden configurar para restablecerse en un intervalo predeterminado. Esto es útil no solo para los escenarios descritos anteriormente, sino también para los títulos que necesitan tener una tabla de clasificación distinta de puntuaciones recientes, que puede usarse para cosas como desafíos del juego, donde quiere permitir que un jugador envíe una invitación a alguien de un nivel de habilidad similar. Establecer un período de restablecimiento significa que los jugadores devueltos en una llamada a GetLeaderboardAroundPlayer, por ejemplo, son los que han jugado recientemente al juego y tienen puntuaciones similares a las del jugador local. También es posible restablecer una estadística como operación manual. Este es un sistema práctico para eliminar los datos que tenga de sus pruebas previas al lanzamiento o de las fases alfa/beta. También es útil para el peor de los casos, cuando se introduce un error en el código del juego que da lugar a puntuaciones desorbitadas. En cada caso, necesita poder dejar la tabla de clasificación limpia, para que los jugadores sientan que tienen una oportunidad justa de entrar en ella.

Restablecer las estadísticas no elimina esos valores, como verá a continuación. Al restablecerse, las estadísticas de PlayFab reciben una nueva versión, lo que convierte la nueva versión en la autoritativa, mientras se conservan las versiones anteriores para su análisis posterior (y para que pueda recompensar a los jugadores en función de sus puntuaciones antiguas).

Configuración de estadísticas restablecibles

Los períodos de restablecimiento de las estadísticas se configuran mediante el conjunto de API de administración o Game Manager. Después se pueden actualizar y consultar mediante Game Manager, la API de servidor y la API de cliente (aunque publicar estadísticas desde el cliente requiere que la opción allow client to post statistics esté establecida en la pestaña Settings->API Features del juego en Game Manager). Describiremos el método de la API para esto, aunque los parámetros definidos aquí son los mismos que se usan en el propio Game Manager. Para configurar las estadísticas, puede usar el método de administración CreatePlayerStatisticDefinition, y el método UpdatePlayerStatisticDefinition para realizar cambios más adelante. En ambos casos, solo hay dos parámetros:

StatisticName: el identificador de cadena de la estadística de jugador.
VersionChangeInterval: el período que define cuándo deben restablecerse automáticamente las estadísticas.

VersionChangeInterval es la clave de esta característica y puede definirse como cada hora, diario, semanal o mensual. También puede establecerse en nunca, si más adelante decide que ya no quiere que la estadística se restablezca de forma periódica. En el ejemplo siguiente, la llamada al método CreatePlayerStatisticDefinition configura la estadística Headshots con un restablecimiento diario, lo que significa que la tabla de clasificación de esta estadística en el juego se restablecerá todos los días a las 00:00 UTC.

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

A continuación se muestra la respuesta de la llamada API anterior.

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

El código que se muestra a continuación es un ejemplo alternativo.

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

La llamada muestra cómo establecer el período de restablecimiento de la estadística en semanal, con la respuesta siguiente.

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

En cada caso, el resultado es PlayerStatisticDefinition, que contiene:

El identificador de cadena de la estadística (StatisticName).
El número de veces que se ha restablecido la estadística (CurrentVersion).
El período definido para cuándo se restablecerá la estadística (VersionChangeInterval).

Los períodos de restablecimiento surten efecto en cuanto se definen, por lo que, en este caso, la segunda llamada significa que el restablecimiento ahora está definido a las 00:00 UTC del lunes por la mañana (medianoche de la noche del domingo/madrugada del lunes, en la zona horaria UTC), independientemente de cuál fuera antes de la llamada. Los demás intervalos de restablecimiento también se definen en UTC, y con Month el restablecimiento se produce a las 00:00 UTC del primer día de cada mes. Para la lista completa, los períodos de restablecimiento son:

Never: deja de crear versiones de la estadística en función del tiempo.
Hour: crea una versión de la estadística al comienzo de cada hora (XX:00 UTC).
Day: crea una versión de la estadística a medianoche (00:00 UTC) cada día.
Week: crea una versión de la estadística a medianoche (00:00 UTC) cada lunes.
Month: crea una versión de la estadística a medianoche (00:00 UTC) el primer día de cada mes.

Estadísticas preexistentes

Se puede consultar la definición de todas las estadísticas definidas en el juego, independientemente de si se configuraron como estadísticas restablecibles o no. Es importante tener esto en cuenta, ya que las estadísticas se pueden crear mediante la llamada UpdatePlayerStatistics. Las estadísticas que no se hayan creado con un período de restablecimiento (VersionChangeInterval) no tendrán uno al principio, por lo que una consulta de la configuración de la estadística devolvería este parámetro establecido en Never. Siguiendo con el ejemplo anterior, si el título también tuviera una estadística llamada FlagsCaptured creada mediante UpdatePlayerStatistics (o creada en Game Manager directamente en un jugador), y hubieran pasado un par de semanas, aparecería como se muestra en la llamada siguiente.

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

Daría como resultado lo siguiente.

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

En este caso, la estadística llamada Headshots tiene definido un intervalo de restablecimiento y CurrentVersion indica que la estadística se ha restablecido dos veces. Mientras tanto, FlagsCaptured no tiene un VersionChangeInterval, que es también la razón por la que CurrentVersion es 0 (ya que nunca ha recibido una nueva versión). Las estadísticas creadas mediante UpdatePlayerStatistics (o el Game Manager de PlayFab) todavía se pueden definir para que tengan un período de restablecimiento mediante UpdatePlayerStatisticDefinition, como se describió anteriormente. Una vez hecho esto, se restablecerán en ese intervalo exactamente igual que si se hubieran definido originalmente con CreatePlayerStatisticDefinition.

Restablecimiento manual de una estadística

Para la situación en la que un error del juego permitió hacer trampas en una estadística, o cuando simplemente necesite restablecer para eliminar las puntuaciones del juego previo al lanzamiento, se puede forzar el restablecimiento de la estadística en Game Manager o mediante una llamada a IncrementPlayerStatisticVersion. Esto restablece inmediatamente las estadísticas actuales que especifique, borrando la tabla de clasificación del juego y proporcionando un lienzo en blanco para que se informen nuevos valores. Para nuestro ejemplo, esta llamada podría tener el aspecto que se muestra a continuación.

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

Esto incrementa una vez más la estadística Headshots y devuelve información sobre la versión que acaba de activarse.

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

En este caso, se devuelve la información de PlayerStatisticVersion, que contiene el identificador de la estadística (StatisticName), así como su número de versión, la hora en que se convirtió en la versión autoritativa (ActivationTime) y el ArchivalStatus (que siempre será NotScheduled para la versión actual). Sin embargo, para una estadística que también tenga un VersionChangeInterval, el restablecimiento manual no cambiará la próxima hora de restablecimiento programada. Si una estadística está programada para restablecerse a diario, y se restablece manualmente a las 23:30 UTC, se restablecerá igualmente de nuevo a medianoche UTC.

Cuándo se produce el restablecimiento

Como se ha indicado, cuando llega el intervalo de restablecimiento, la estadística recibirá una nueva versión, de modo que una nueva versión estará disponible de inmediato, mientras que la versión antigua de esa estadística se archiva para su recuperación posterior. Una vez que llega el intervalo de restablecimiento (o se realiza un restablecimiento manual) y la estadística recibe una nueva versión, se aceptarán escrituras en la versión antigua durante un máximo de diez minutos. Más allá de ese punto, la estadística queda bloqueada, lo que impide futuras actualizaciones. Una vez expiradas, las estadísticas comienzan el proceso de archivo, para que el título pueda recuperarlas más adelante. Las fases del proceso de archivo de una estadística son:

NotScheduled: el archivo de la estadística no ha comenzado (normalmente solo para la versión de la estadística activa actualmente).
Scheduled: el proceso de archivo se ha programado, pero aún no está en marcha.
InProgress: se está realizando una copia de seguridad de la estadística en el archivo.
Failed: se produjo un error inesperado (en este caso, póngase en contacto con nuestros foros de soporte).
Complete: esta versión de la estadística se ha archivado.

Todas las versiones pasadas y actuales de una estadística se pueden consultar mediante GetPlayerStatisticVersions. Esto devuelve la información de cada versión, como se muestra en el ejemplo anterior de restablecimiento manual. En otras palabras, esta llamada debería parecerse a la que se presenta a continuación.

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

Esto podría dar como resultado que se devuelva la información siguiente para nuestro título de ejemplo.

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

Además de los valores devueltos por IncrementPlayerStatisticVersion, la respuesta también incluye las marcas de tiempo de cuándo expiró cada versión (DeactivationTime) para las versiones anteriores a la activa actual, y una URL para descargar el CSV que contiene el registro completo de la tabla de clasificación antigua, una vez completado el proceso de archivo (ArchiveDownloadUrl).

Lectura y escritura en versiones de estadísticas

Por último, desde el punto de vista de las API de servidor y cliente, las llamadas son muy similares a las que conoce de las llamadas originales de estadísticas de usuario y personaje de PlayFab. La diferencia es que ahora la versión forma parte de la solicitud o de la respuesta. Al recuperar las estadísticas, se devuelve el valor de la versión actual de la estadística, así como el propio número de versión. Los ejemplos siguientes muestran cómo realizar la llamada para la estadística Headshots, así como los datos devueltos.

Solicitud del servidor

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

Respuesta del servidor

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

Solicitud del cliente

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

Respuesta del cliente

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

Mientras tanto, la llamada Update acepta una versión opcional, para permitir que el título controle qué versión se está actualizando, en los casos en que la versión pueda haberse incrementado durante el juego.

En este ejemplo, si el título fuera a escribir en la versión anterior mientras todavía es posible, escribiría en la versión 2, como se muestra a continuación.

Solicitud del 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())
    );
}

Respuesta del servidor

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

Solicitud del 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())
    );
}

Respuesta del cliente

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

Pero recuerde: aunque se puede escribir en la versión expirada durante un máximo de 10 minutos, cualquier intento de escribir en esa versión más allá de ese tiempo fallará, con una respuesta como la que se muestra a continuación.

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

Recursos

Para que la información sea completa, esta sección proporciona una lista de todas las enumeraciones, clases y métodos de API descritos anteriormente, con descripciones breves.

Enumeraciones base

Interval: período según el cual se restablecerá la estadística (tabla de clasificación):
- Never
- Hour
- Day
- Week
- Month
StatisticVersionArchivalStatus: el estado del proceso de guardado de los valores de estadísticas de jugador de una versión en un archivo descargable:
- NotScheduled
- Scheduled
- InProgress
- Failed
- Complete

Clases base y sus miembros

PlayerStatisticDefinition
- StatisticName (string): el nombre único de la estadística.
- CurrentVersion (string): la versión activa actual de la estadística, que se incrementa cada vez que se restablece la estadística.
- VersionChangeInterval (Interval): el intervalo en el que se restablecen los valores de la estadística para todos los jugadores.
PlayerStatisticVersion
- StatisticName (string): el nombre de la estadística cuando la versión se activó.
- Version (string): la versión de la estadística (un número hexadecimal codificado como cadena).
- ScheduledVersionChangeIntervalTime (DateTime): la hora a la que estaba programado que la versión de la estadística se activara, en función del ResetInterval configurado.
- CreatedTime (DateTime): la hora en que la versión de la estadística se activó.
- ArchivalStatus (StatisticVersionArchivalStatus): el estado del proceso de guardado de los valores de estadísticas de jugador de esta versión en un archivo descargable, si está configurado.
- ResetInterval (Interval): el intervalo de restablecimiento que desencadenó la activación de la versión, si está configurado.
StatisticValue
- StatisticName (string): el nombre único de la estadística.
- Value (Int32): el valor de la estadística para el jugador.
- Version (string): para un valor de estadística existente de un jugador, la versión de la estadística cuando se cargó.
StatisticUpdate
- StatisticName (string): el nombre único de la estadística.
- Version (string): para las actualizaciones de un valor de estadística de un jugador, la versión de la estadística que se va a actualizar
- Value (Int32): el valor de la estadística para el jugador.

Métodos de la API de administración

CreatePlayerStatisticDefinition
- CreatePlayerStatisticDefinitionRequest
  - Name (string): longitud mínima 1, longitud máxima 128; el nombre único de la estadística.
  - (VersionChangeInterval) (Interval): el intervalo en el que se restablecen los valores de la estadística para todos los jugadores (los restablecimientos comienzan en el siguiente límite de intervalo).
- CreatePlayerStatisticDefinitionResult
  - Statistic (PlayerStatisticDefinition): la definición de la estadística creada.
UpdatePlayerStatisticDefinition
- UpdatePlayerStatisticDefinitionRequest
  - StatisticName (string): el nombre único de la estadística.
  - VersionChangeInterval (Interval): el intervalo en el que se restablecen los valores de la estadística para todos los jugadores (los restablecimientos comienzan en el siguiente límite de intervalo).
- UpdatePlayerStatisticDefinitionResult
  - Statistic (PlayerStatisticDefinition): la definición de la estadística creada.
GetPlayerStatisticDefinitions
- GetPlayerStatisticDefinitionsRequest (sin parámetros).
- GetPlayerStatisticDefinitionsResult
  - Statistics (PlayerStatisticDefinition[]): la matriz de definiciones para el restablecimiento.
GetPlayerStatisticVersions
- GetPlayerStatisticVersionsRequest
  - StatisticName (string): el nombre único de la estadística.
- GetPlayerStatisticVersionsResult
  - StatisticVersions (PlayerStatisticVersion[]): el historial de cambios de versión de la estadística (todas las versiones).
IncrementPlayerStatisticVersion
- IncrementPlayerStatisticVersionRequest
  - StatisticName (string): el nombre único de la estadística.
- IncrementPlayerStatisticVersionResult
  - StatisticVersion (PlayerStatisticVersion): la versión de la estadística que expiró como resultado de esta operación (y su estado de archivo).

Métodos de la API de cliente

GetPlayerStatistics
- GetPlayerStatisticsRequest
  - StatisticNames (string[]): matriz de estadísticas que se devolverán, por sus nombres únicos.
- GetPlayerStatisticsResult
  - Statistics (StatisticValue[]): matriz de datos StatisticValue para todas las estadísticas solicitadas.
UpdatePlayerStatistics
- UpdatePlayerStatisticsRequest
  - Statistics (StatisticUpdate[]): la estadística que se va a actualizar, con los valores proporcionados.
- UpdatePlayerStatisticsResult (sin parámetros).

Métodos de la API de servidor

GetPlayerStatistics
- GetPlayerStatisticsRequest
  - PlayFabId (string): el identificador de PlayFab del jugador cuyas estadísticas se están actualizando.
  - StatisticNames (string[]): matriz de estadísticas que se devolverán, por sus nombres únicos.
- GetPlayerStatisticsResult
  - Statistics (StatisticValue[]): matriz de datos StatisticValue para todas las estadísticas solicitadas.
UpdatePlayerStatistics
- UpdatePlayerStatisticsRequest
  - PlayFabId (string): el identificador de PlayFab del jugador cuyas estadísticas se están actualizando.
  - Statistics (StatisticUpdate[]): la estadística que se va a actualizar, con los valores proporcionados.
- UpdatePlayerStatisticsResult (sin parámetros).

​Estadísticas y tablas de clasificación

​Configuración de estadísticas restablecibles

​Estadísticas preexistentes

​Restablecimiento manual de una estadística

​Cuándo se produce el restablecimiento

​Lectura y escritura en versiones de estadísticas

​Solicitud del servidor

​Respuesta del servidor

​Solicitud del cliente

​Respuesta del cliente

​Solicitud del servidor

​Respuesta del servidor

​Solicitud del cliente

​Respuesta del cliente

​Recursos

​Enumeraciones base

​Clases base y sus miembros

​Métodos de la API de administración

​Métodos de la API de cliente

​Métodos de la API de servidor

Estadísticas y tablas de clasificación

Configuración de estadísticas restablecibles

Estadísticas preexistentes

Restablecimiento manual de una estadística

Cuándo se produce el restablecimiento

Lectura y escritura en versiones de estadísticas

Solicitud del servidor

Respuesta del servidor

Solicitud del cliente

Respuesta del cliente

Solicitud del servidor

Respuesta del servidor

Solicitud del cliente

Respuesta del cliente

Recursos

Enumeraciones base

Clases base y sus miembros

Métodos de la API de administración

Métodos de la API de cliente

Métodos de la API de servidor