Creación de una estadística básica

En este tutorial, le mostramos cómo crear una estadística básica con nuestro nuevo servicio de estadísticas. Comencemos con un ejemplo de un juego de disparos que quiere registrar cada vez que un jugador acierta un tiro a larga distancia.

Creación de una estadística

El primer paso es crear una definición de estadística que incluya los elementos principales para realizar el seguimiento de los tiros a larga distancia. Para nuestro juego de disparos, solo necesitamos una columna para la distancia del tiro. En el ejemplo siguiente se muestra cómo crear la definición de estadística mediante el SDK de C#.

public static async Task CreateStatisticDefinitionAsync(PlayFabAuthenticationContext context, string statName)
{
    PlayFabProgressionInstanceAPI statsAPI = new PlayFabProgressionInstanceAPI(context);
    CreateStatisticDefinitionRequest statDefinitionRequest = new CreateStatisticDefinitionRequest()
    {
        Name = statName,
        AuthenticationContext = context,
        EntityType = "title_player_account",
        VersionConfiguration = new VersionConfiguration()
        {
            MaxQueryableVersions = 1,
            ResetInterval = ResetInterval.Manual,
        },
        Columns = new List<StatisticColumn>()
        {
            new StatisticColumn()
            {
                Name = "Distance",
                AggregationMethod = StatisticAggregationMethod.Max,
            }
        },
    };
    
    PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> createStatDefResult = await statsAPI.CreateStatisticDefinitionAsync(statDefinitionRequest);
}

Ahora, expliquemos algunos elementos clave de este ejemplo:

AuthenticationContext: Este parámetro controla toda la autenticación detrás de cada solicitud a nuestros servicios. Para obtener una explicación detallada, puede consultar la página siguiente: Inicio rápido de estadísticas.
Name: Este parámetro le ayuda a identificar la definición de estadísticas. Es importante usar aquí algo relevante, ya que se va a usar para realizar otras solicitudes de recuperación de información.
EntityType: Este parámetro especifica el tipo de entidad para el que desea crear la estadística. Puede obtener más información aquí: Modelo de programación de entidades.
VersionConfiguration: Este parámetro le permite establecer una estrategia de control de versiones para las estadísticas que se restablecen después de un período determinado. Este concepto se trata en profundidad aquí: Estadísticas de temporada.
Columns: Aquí, definimos el número de columnas de nuestra estadística, con un máximo de 5 por definición. En este ejemplo, solo establecemos una columna para los tiros a larga distancia. También definimos AggregationMethod como Max, lo que significa que la estadística solo se va a actualizar cuando el nuevo valor sea mayor que el anterior.
- AggregationMethod tiene cuatro valores posibles:
  - Max: El nuevo valor debe ser mayor que el anterior.
  - Min: El nuevo valor debe ser menor que el anterior.
  - Last: Siempre se actualiza con el valor más reciente.
  - Sum: El valor anterior y el nuevo se suman.

Con toda la información clara, ya está listo para ejecutar el ejemplo y crear su primera estadística.

Obtención de una definición de estadística

Antes de agregar datos a esta estadística, queremos asegurarnos de que se creó correctamente. Para realizar esta acción, proporcionamos un ejemplo de cómo puede recuperar la definición de estadística.

public static async Task GetStatisticDefinition(PlayFabAuthenticationContext context, string statName)
{
    PlayFabProgressionInstanceAPI statsAPI = new PlayFabProgressionInstanceAPI(context);
    GetStatisticDefinitionRequest statDefReq = new GetStatisticDefinitionRequest()
    {
        Name = statName
    };

    PlayFabResult<GetStatisticDefinitionResponse> getStatDefResult = await statsAPI.GetStatisticDefinitionAsync(statDefReq)
}

Para recuperar la definición de estadística, especifique el nombre de la estadística que creó. Si tiene varias definiciones de estadísticas, puede usar el ejemplo siguiente para obtener todas sus definiciones de estadísticas con una sola solicitud.

public static async Task GetStatisticDefinitions(PlayFabAuthenticationContext context)
{
     PlayFabProgressionInstanceAPI leaderboardsAPI = new PlayFabProgressionInstanceAPI(context);
     ListStatisticDefinitionsRequest request = new ListStatisticDefinitionsRequest();
     PlayFabResult<ListStatisticDefinitionsResponse> getStatDefsResult = await leaderboardsAPI.ListStatisticDefinitionsAsync(request);
           
}

Actualización de una definición de estadística

Si desea actualizar la definición de estadística, puede hacerlo de la siguiente manera:

public static async Task UpdateStatisticDefinitionAsync(PlayFabAuthenticationContext context, string statisticName, VersionConfiguration version)
{
    PlayFabProgressionInstanceAPI statsAPI = new PlayFabProgressionInstanceAPI(context);
    UpdateStatisticDefinitionRequest updateStatDefinitionRequest = new UpdateStatisticDefinitionRequest()
    {
        AuthenticationContext = context,
        Name = statisticName,
        VersionConfiguration = version

    };
    PlayFabResult<PlayFab.ProgressionModels.EmptyResponse> updateStatDefinitionResult = await statsAPI.UpdateStatisticDefinitionAsync(updateStatDefinitionRequest);

}

Tenga en cuenta que Columns, EntityType y ResetInterval no se pueden modificar como parte de la actualización.

### Eliminación de una definición de estadística

Si desea eliminar la definición de estadística para agregar más columnas o corregir algunos errores, puede hacerlo de la siguiente manera:

 
``` C#

public static async Task DeleteStatisticDefinition(PlayFabAuthenticationContext context, string statName)
\{
    PlayFabProgressionInstanceAPI statsAPI = new PlayFabProgressionInstanceAPI(context);
    DeleteStatisticDefinitionRequest deleteStatDefRequest = new DeleteStatisticDefinitionRequest()
    \{
        AuthenticationContext = context,
        Name = statName,
    \};
    
    PlayFabResult<PlayFab.LeaderboardsModels.EmptyResponse> statResponse = await statsAPI.DeleteStatisticDefinitionAsync(deleteStatDefRequest);    
\}

Adición de datos a una estadística

Siguiendo con nuestro ejemplo del juego de disparos, ahora sabemos cómo crear una definición de estadística, recuperarla y eliminarla si es necesario. Nuestro siguiente paso es comenzar a agregar datos a nuestra estadística. Tenga en cuenta que estas estadísticas están basadas en entidades, lo que significa que las entradas son entidades. En nuestro ejemplo concreto, usamos el tipo de entidad title_player_account, por lo que nuestra estadística realiza el seguimiento de la información de un jugador. Sin embargo, recuerde que también hay otros tipos de entidad que puede usar. Puede consultarlos aquí: Tipos de entidad integrados disponibles. Ahora veamos cómo podemos agregar datos a nuestra estadística.

public static async Task UpdateStatisticForPlayer(PlayFabAuthenticationContext context, string statName, string entityId, int score)
\{
    PlayFabProgressionInstanceAPI statsAPI = new PlayFabProgressionInstanceAPI(context);
    UpdateStatisticsRequest updateStatRequest = new UpdateStatisticsRequest()
    \{
        Entity = new PlayFab.LeaderboardsModels.EntityKey()
        \{
            Id = entityId,
            Type = EntityType
        \},
        AuthenticationContext = context,
        Statistics = new List<PlayFab.LeaderboardsModels.StatisticUpdate>() 
        \{
            new PlayFab.LeaderboardsModels.StatisticUpdate() 
            \{
                Name = statName,
                Scores = new List<string> \{ score.ToString()\},
            \}
        \}
    \};

    PlayFabResult<UpdateStatisticsResponse> updateResult = await statsAPI.UpdateStatisticsAsync(updateStatRequest);
\}

Ahora, expliquemos algunos elementos clave de este ejemplo:

Entity: Este parámetro corresponde a la entidad desde la que queremos realizar la actualización de la estadística.
Statistics: Este parámetro corresponde al conjunto real de estadísticas de una entidad.
StatisticUpdate: Este parámetro corresponde a los valores de estadísticas que se van a agregar.
- Scores: Este parámetro corresponde a la lista de puntuaciones que puede agregar a una entidad. Recuerde que las estadísticas pueden tener más de una columna. Puede consultar estos conceptos en profundidad aquí: Más operaciones con estadísticas
- Name: Este parámetro corresponde al nombre de la estadística establecido al crear la definición de estadística.

Con estos conceptos claros, ya está listo para agregar datos a su estadística.

Recuperación de datos de una estadística

Hagamos un resumen rápido. En este punto, creó una estadística, comprobó todos los detalles de configuración y comenzó a agregarle datos. Ahora, imaginemos que algunos jugadores ya comenzaron a usar su juego, todos con impresionantes tiros a larga distancia. Queremos consultar uno de ellos. En el ejemplo siguiente, le mostramos cómo realizar esta acción.

public static async Task GetStatsForEntity(PlayFabAuthenticationContext context, string entityId)
\{
    PlayFabProgressionInstanceAPI statsAPI = new PlayFabProgressionInstanceAPI(context);

    GetStatisticsRequest request = new GetStatisticsRequest()
    \{
        AuthenticationContext = context,
        Entity = new PlayFab.LeaderboardsModels.EntityKey()
        \{
            Id = entityId,
            Type = EntityType
        \},
    \};
    
    PlayFabResult<GetStatisticsResponse> result = await statsAPI.GetStatisticsAsync(request);

    Console.WriteLine("Stats for entity: " + result.Result.Entity.ToString());
    foreach (KeyValuePair<string, PlayFab.LeaderboardsModels.EntityStatisticValue> statValuePair in result.Result.Statistics)
    \{
        Console.WriteLine($"\{statValuePair.Value.Name\} : \{string.Join('|', statValuePair.Value.Scores)\}");
    \}
\}

Aquí consultamos todas las estadísticas asociadas a una entidad y luego imprimimos el nombre con su valor correspondiente.

Eliminación de valores de estadísticas

Nuestras estadísticas funcionan según lo previsto y tenemos muchos jugadores en su juego. Sin embargo, comenzamos a notar algún comportamiento inusual en el juego. Así que decidimos empezar de cero y eliminar los datos de nuestra estadística. En el ejemplo siguiente, puede ver cómo eliminar datos de su estadística.

 public static async Task DeleteStats(PlayFabAuthenticationContext context, string entityId, List<StatisticDelete> stats)
 \{
     PlayFabProgressionInstanceAPI statsAPI = new PlayFabProgressionInstanceAPI(context);
     DeleteStatisticsRequest statsDelReq = new DeleteStatisticsRequest()
     \{
         Entity = new PlayFab.LeaderboardsModels.EntityKey()
         \{
            Id = entityId,
            Type = EntityType
         \},
         Statistics = stats
     \};
 
     PlayFabResult<DeleteStatisticsResponse> delStatsResult = await statsAPI.DeleteStatisticsAsync(statsDelReq);     
 \}

Ahora, expliquemos algunos elementos clave de este ejemplo:

Entity: Este parámetro es la entidad de la que desea eliminar.
List<StatisticDelete>: Este parámetro es una lista de los nombres de las estadísticas que desea eliminar.

Conclusiones

En este tutorial, aprendimos a realizar las siguientes operaciones:

Crear una estadística
Comprobar la configuración de una estadística
Actualizar la configuración de una estadística
Eliminar la configuración de la estadística
Rellenar la estadística
Eliminar entradas de la estadística.

XBOX Services

PlayFab