Canalización de eventos

La canalización de eventos es una característica que forma parte del SDK de PlayFab Services y cuyo propósito principal es permitir a los desarrolladores de juegos enviar eventos para almacenarlos en PlayFab Insights. Permite al desarrollador especificar el tamaño del lote, la frecuencia de envío y otros aspectos de una solución de telemetría adecuada. Ayuda a aliviar esa carga del desarrollador del juego y a gestionar todos esos aspectos en su nombre. Existe compatibilidad con canalizaciones de eventos configurables. Un título puede contener una o varias de estas canalizaciones y cada una puede configurarse con sus propias propiedades. Repasemos algunos de los conceptos básicos de la canalización.

Tipos de canalización

El tipo de canalización está directamente relacionado con el tipo de eventos que emite una canalización. Hay dos tipos diferentes de canalizaciones que un desarrollador puede crear instancias:

Canalización de eventos de telemetría: solo puede emitir eventos de telemetría y usa la API REST Write Telemetry Events.
Canalización de eventos de PlayStream: solo puede emitir eventos de PlayStream y usa la API REST Write Events.

Puede tener varias canalizaciones con diferentes tipos y configuraciones, pero cabe mencionar que el tipo de canalización no puede cambiarse después de la creación; sería necesario volver a crear una instancia de la canalización.

Tipos de autenticación

Otra pieza importante de la creación de la canalización es el tipo de autenticación. Hay dos mecanismos de autenticación compatibles para los eventos de PlayFab: la autenticación de entidad y la autenticación con clave de telemetría. La autenticación de entidad se usa cuando el desarrollador del juego quiere vincular sus eventos a una entidad concreta para su posterior agregación o análisis. Por ejemplo, el desarrollador del juego podría registrar eventos relacionados con las acciones del jugador para realizar análisis de comportamiento adicionales de los jugadores del título que permitan la segmentación. La autenticación con clave de telemetría se usa cuando el desarrollador del juego quiere registrar eventos que no necesitan estar vinculados necesariamente a una entidad. Por ejemplo, antes de tener un jugador con la sesión iniciada, el título puede empezar a enviar eventos relacionados con el rendimiento o con métricas específicas que quiera recopilar para su análisis posterior. Esto puede hacerse sin necesidad de pasar por el proceso normal de autenticación de entidad. Combinaciones compatibles de tipo de autenticación y tipo de evento

	Autenticación de entidad	Autenticación con clave de telemetría
Eventos de telemetría	Válida	Válida
Eventos de PlayStream	Válida	No válida

Autenticación de entidad

Este tipo de autenticación es el método de autenticación de PlayFab normal y más común. Está estrechamente relacionado con una entidad específica y requiere llamar a las API de inicio de sesión de PlayFab correspondientes para obtener un token de entidad que se usará en cualquier llamada posterior. La lista siguiente representa los diferentes tipos de entidades que pueden usarse con la autenticación de entidad.

namespace: la entidad namespace hace referencia a toda la información global de todos los títulos de su estudio.
title: la entidad title hace referencia a toda la información global de ese título.
master_player_account: la master_player_account es una entidad de jugador compartida por todos los títulos de su estudio.
title_player_account: para la mayoría de los desarrolladores, title_player_account representa al jugador de la forma más tradicional.
character: la entidad character es una subentidad de title_player_account.
group: la entidad group es un contenedor para otras entidades. Actualmente está limitada a jugadores y personajes.

Para obtener más información sobre los diferentes tipos de entidades, consulte Tipos de entidades integrados. Además, la entidad de la canalización puede actualizarse después de la creación de la canalización proporcionando un PFEntityHandle válido. Así, el desarrollador del juego puede agregar una entidad para empezar a vincular sus eventos a ella (consulte la sección Cambio a autenticación de entidad o actualización de la entidad) o incluso eliminarla si quiere registrar cosas que no están relacionadas con una entidad (consulte la sección Cambio a autenticación con clave de telemetría). Si existe una entidad en la canalización, siempre tiene prioridad sobre la autenticación con clave de telemetría.

Autenticación con clave de telemetría

La autenticación con clave de telemetría no requiere un token de entidad, por lo que no está vinculada a ninguna entidad específica. Si se usa la autenticación con clave de telemetría, se requiere una estructura PFEventPipelineTelemetryKeyConfig durante la creación de la canalización. Esta estructura tiene dos partes principales:

Una clave de telemetría que consiste en una cadena que se crea y administra a través de PlayFab Game Manager.
Un PFServiceConfigHandle que permite al SDK saber cuál es la configuración de servicio correcta que debe usarse para cargar los eventos. El identificador de configuración de servicio se crea durante la inicialización del SDK llamando a PFServiceConfigCreateHandle.

Si el desarrollador quiere usar una clave de telemetría, es importante proporcionarla en el momento de la creación de la canalización, ya que no hay forma de agregar una clave de telemetría después de que se haya creado la instancia de la canalización. Cabe mencionar que la autenticación con clave de telemetría solo está disponible para los eventos de telemetría; no es compatible con los eventos de PlayStream.

Configuración de la canalización de eventos

Como se mencionó anteriormente, la canalización de eventos tiene algunas propiedades configurables que pueden proporcionarse después de la creación de la canalización a través del parámetro de estructura PFEventPipelineConfig. Las propiedades configurables son:

maxEventsPerBatch: el número máximo de eventos que se agrupan en lotes antes de escribirlos en PlayFab.
maxWaitTimeInSeconds: el tiempo máximo que la canalización espera antes de enviar un lote incompleto.
pollDelayInMs: cuánto tiempo esperará la canalización para volver a leer del búfer de eventos después de vaciarlo.
compressionLevel: define el nivel de compresión que se usa en el algoritmo de compresión. Para obtener más detalles sobre la compresión, consulte Compresión GZIP.
retryOnDisconnect: la canalización de eventos reintentará enviar los eventos que produjeron un error debido a una conexión perdida. Solo está disponible para la canalización de eventos de telemetría.
bufferSize: el límite de la cantidad de eventos en el búfer de la canalización.

Valores predeterminados

Propiedad	Canalización de telemetría	Canalización de PlayStream
maxEventsPerBatch	5	5
maxWaitTimeInSeconds	3	3
pollDelayInMs	3000	10
compressionLevel	None (deshabilitado)	None (deshabilitado)
retryOnDisconnect	true	N/D
bufferSize	1024	1024

En el caso de que PFEventPipelineConfig solo tenga algunas propiedades especificadas, las que están vacías se sobrescriben y usan los valores predeterminados. Para ver un ejemplo de cómo puede actualizarse cualquiera de estas propiedades de la canalización de eventos, consulte Actualización de la configuración de la canalización.

Compresión GZIP

La canalización de eventos ofrece la opción de comprimir las cargas del cuerpo mediante el estándar de compresión GZIP. El nivel de compresión deseado puede especificarse dentro de la estructura PFEventPipelineConfig que forma parte de los parámetros de la API PFEventPipelineUpdateConfiguration. Un nivel de compresión más bajo logra menos compresión, pero tiene la velocidad más alta, y un nivel de compresión más alto logra mejores tasas de compresión, pero tiene la velocidad de compresión más lenta. La diferencia en las tasas de compresión depende totalmente del tipo de datos que se envían. Según el tamaño y la aleatoriedad de los datos, las tasas de compresión pueden ser las mismas incluso en niveles diferentes. Ventajas y desventajas: Usar compresión aumenta el tiempo de CPU debido a la complejidad añadida de ejecutar un algoritmo de compresión, pero, por otro lado, la carga del cuerpo en la red disminuye drásticamente. Por lo tanto, según las necesidades y los recursos del juego, depende del desarrollador del juego decidir si debe usarse la compresión. Según la validación interna, hay un aumento medio del 20 % en el tiempo de CPU y una disminución media del 91 % en el tamaño del cuerpo de la carga. Estos porcentajes podrían variar en gran medida según el tamaño de la carga y la complejidad de los datos que se comprimen.

Controladores de eventos

Como parte de la creación de la canalización, los desarrolladores de juegos pueden proporcionar dos controladores de eventos opcionales que se invocan cuando se cargan los eventos. Sin embargo, si el desarrollador del juego quiere una experiencia de “activar y olvidar”, puede omitir el suministro de los controladores de eventos. Los controladores de eventos que pueden proporcionarse son los siguientes:

PFEventPipelineBatchUploadSucceededEventHandler: como su nombre indica, recibe todos los eventos que se cargan correctamente en PlayFab.
PFEventPipelineBatchUploadFailedEventHandler: recibirá todos los eventos con error después de pasar por la lógica de reintentos de la canalización.

Ejemplos de creación de canalizaciones

A continuación puede encontrar diferentes ejemplos de cómo crear una instancia de una canalización de eventos según los temas tratados anteriormente.

Creación de una canalización de eventos de telemetría con autenticación de entidad Si el desarrollador quiere enviar eventos de telemetría y no necesita usar la autenticación con clave de telemetría, la API PFEventPipelineCreateTelemetryPipelineHandleWithEntity sirve para este propósito, como se ve en el ejemplo siguiente:

void EventPipelineCreation(PFEntityHandle entityHandle, XTaskQueueHandle taskQueueHandle)
{
    PFEventPipelineHandle handle;

    HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithEntity(
        entityHandle,                       // entityHandle
        taskQueueHandle,                    // queue
        nullptr,                            // eventPipelineBatchUploadedEventHandler
        nullptr,                            // eventPipelineBatchFailedEventHandler
        nullptr,                            // handlerContext
        &handle                             // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed creating event pipeline: 0x%x\r\n", hr);
        return;
    }
}

En este ejemplo se muestra cómo crear una canalización de eventos de telemetría que usa autenticación de entidad y no tiene controladores. Esto significa que la canalización activa los eventos y se olvida del resultado.

Creación de una canalización de eventos de telemetría con autenticación con clave de telemetría Si el desarrollador quiere enviar eventos de telemetría y necesita usar la autenticación con clave de telemetría, la API PFEventPipelineCreateTelemetryPipelineHandleWithKey sirve para este propósito, como se ve en el ejemplo siguiente:

void EventPipelineCreation(PFServiceConfigHandle serviceConfigHandle, XTaskQueueHandle taskQueueHandle)
{
    PFEventPipelineHandle handle;

    PFEventPipelineTelemetryKeyConfig telemetryKeyConfig
    {
        "myTelemetryKey",                   // telemetryKey
        serviceConfigHandle,                // serviceConfigHandle
    };

    HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithKey(
        &telemetryKeyConfig,                // eventPipelineTelemetryKeyConfig
        taskQueueHandle,                    // queue
        nullptr,                            // eventPipelineBatchUploadedEventHandler
        nullptr,                            // eventPipelineBatchFailedEventHandler
        nullptr,                            // handlerContext
        &handle                             // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed creating event pipeline: 0x%x\r\n", hr);
        return;
    }
}

En este ejemplo se muestra cómo crear una canalización de eventos de telemetría que no usa autenticación de entidad. La canalización de eventos empieza a cargar eventos mediante la clave de telemetría con la posibilidad de agregar una entidad más adelante. Consulte Cambio a autenticación de entidad o actualización de la entidad

Creación de una canalización de eventos de PlayStream Si el desarrollador quiere enviar eventos de PlayStream, la API PFEventPipelineCreatePlayStreamPipelineHandle sirve para este propósito, como se ve en el ejemplo siguiente:

void EventPipelineCreation(PFEntityHandle entityHandle, XTaskQueueHandle taskQueueHandle)
{
    PFEventPipelineHandle handle;

    HRESULT hr = PFEventPipelineCreatePlayStreamPipelineHandle(
        entityHandle,                       // entityHandle
        taskQueueHandle,                    // queue
        nullptr,                            // eventPipelineBatchUploadedEventHandler
        nullptr,                            // eventPipelineBatchFailedEventHandler
        nullptr,                            // handlerContext
        &handle                             // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed creating event pipeline: 0x%x\r\n", hr);
        return;
    }
}

En este ejemplo se muestra cómo se crea una canalización de eventos de PlayStream que usa autenticación de entidad y no tiene controladores. Lo que significa que la canalización activa los eventos y se olvida del resultado.

Canalización de eventos con controladores de eventos En este ejemplo se muestra cómo se proporcionarían controladores de eventos a las API de creación de canalizaciones.

void CALLBACK OnBatchUploadedHandler(void* context, PFUploadedEvent const* const* events, size_t eventsCount)
{
    // Handle response
}

void CALLBACK OnBatchUploadFailedHandler(void* context, HRESULT hr, const char* errorMessage, PFEvent const* const* events, size_t eventsCount)
{
    // Handle response
}

void EventPipelineCreation(PFEntityHandle entityHandle, XTaskQueueHandle taskQueueHandle)
{
    PFEventPipelineHandle handle;

    HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithEntity(
        entityHandle,                       // entityHandle
        taskQueueHandle,                    // queue
        OnBatchUploadedHandler,             // eventPipelineBatchUploadedEventHandler
        OnBatchUploadFailedHandler,         // eventPipelineBatchFailedEventHandler
        nullptr,                            // handlerContext
        &handle                             // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed creating event pipeline: 0x%x\r\n", hr);
        return;
    }
}

Como se ve en el ejemplo, OnBatchUploadedHandler y OnBatchUploadFailedHandler se declaran como dos funciones de devolución de llamada diferentes que se pasan cuando se crea la canalización de eventos. Cada resultado asociado a un evento se devuelve en una de estas dos funciones, dependiendo de si el resultado fue correcto o erróneo. Depende del desarrollador del juego cómo gestionar el resultado.

Emisión de eventos

Emitir eventos es una operación sencilla una vez que la canalización de eventos ya está creada. El desarrollador del juego debe llamar a la API PFEventPipelineEmitEvent, que recibe el identificador de la canalización de eventos existente y el evento que quiere enviar.

void EmitEvent(PFEventPipelineHandle handle)
{
    PFEvent myEvent
    {
        nullptr,
        "custom.playfab.events.PlayFab.Test.TelemetryEventPipelineTests",
        "TelemetryEvent",
        nullptr,
        "{}"
    };

    HRESULT hr = PFEventPipelineEmitEvent(
        handle,
        &myEvent
    );

    if (FAILED(hr))
    {
        printf("Failed emitting event: 0x%x\r\n", hr);
        return;
    }
}

Es importante tener en cuenta que, al usar la autenticación con clave de telemetría, el único valor válido para entityType como parte de PFEntityKey es “external”. Cualquier otro tipo de entidad se rechaza y los eventos no se cargan. Ejemplo de una PFEntityKey válida al usar autenticación con clave de telemetría:

void EmitEvent(PFEventPipelineHandle handle)
{
    PFEntityKey pfEntityKey{ "my-unique-ID", "external" };  // Note the "external" value

    PFEvent myEvent
    {
        &pfEntityKey,
        "custom.playfab.events.PlayFab.Test.EventsWithTelemetryKey",
        "TelemetryEvent",
        nullptr,
        "{}"
    };

    HRESULT hr = PFEventPipelineEmitEvent(
        handle,
        &myEvent
    );

    if (FAILED(hr))
    {
        printf("Failed emitting event: 0x%x\r\n", hr);
        return;
    }
}

Si se supera el límite de tamaño del búfer cuando se emite un evento, encontrará un error del SDK como el siguiente:

E_PF_API_CLIENT_REQUEST_RATE_LIMIT_EXCEEDED (0x892354dd)

Asegúrese de establecer un tamaño de búfer adecuado para sus necesidades.

Cambio a autenticación de entidad o actualización de la entidad

Si una canalización se creó usando solo una configuración de clave de telemetría, hay una forma de cambiar a la autenticación de entidad o, si lo desea, de actualizar su canalización para que use una entidad diferente. Mediante PFEventPipelineAddUploadingEntity, es posible adjuntar una entidad a una canalización en ejecución sin necesidad de reinicializarla. También reemplaza la entidad existente, si la hay. Ejemplo: Se crea una canalización de eventos de telemetría con la configuración de clave de telemetría al principio de la ejecución del título. Las posibles razones para ello son que todavía no hay una identidad de jugador o simplemente que aún no queremos registrar nada relacionado con un jugador.

void EventPipelineCreation(PFServiceConfigHandle serviceConfigHandle, XTaskQueueHandle taskQueueHandle)
{
    PFEventPipelineHandle handle;

    PFEventPipelineTelemetryKeyConfig telemetryKeyConfig
    {
        "myTelemetryKey",                   // telemetryKey
        serviceConfigHandle,                // serviceConfigHandle
    };

    HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithKey(
        &telemetryKeyConfig,                // eventPipelineTelemetryKeyConfig
        taskQueueHandle,                    // queue
        nullptr,                            // eventPipelineBatchUploadedEventHandler
        nullptr,                            // eventPipelineBatchFailedEventHandler
        nullptr,                            // handlerContext
        &handle                             // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed creating event pipeline: 0x%x\r\n", hr);
        return;
    }
}

Después, un jugador ha iniciado sesión o simplemente queremos empezar a enviar eventos adjuntos a una entidad concreta, por lo que podemos llamar a PFEventPipelineAddUploadingEntity con el identificador de la canalización de eventos existente y el identificador de entidad deseado de la manera siguiente:

void EventPipelineUpdateEntity(PFEventPipelineHandle handle)
{
    HRESULT hr = PFEventPipelineAddUploadingEntity(
        handle,                 // eventPipelineHandle
        entityHandle            // entityHandle
    );

    if (FAILED(hr))
    {
        printf("Failed adding uploading entity: 0x%x\r\n", hr);
        return;
    }
}

Después de esta llamada, la canalización empezará a registrar cualquier evento posterior vinculado a esa entidad.

Cambio a autenticación con clave de telemetría

Ampliando el escenario anterior, si el desarrollador quiere volver a la autenticación con clave de telemetría y desvincular el registro de eventos de la entidad, puede llamar a PFEventPipelineRemoveUploadingEntity y pasar el identificador de la canalización de eventos de esta manera:

void EventPipelineRemoveEntity(PFEventPipelineHandle handle)
{
    HRESULT hr = PFEventPipelineRemoveUploadingEntity(
        handle                  // eventPipelineHandle
    );

    if (FAILED(hr))
    {
        printf("Failed removing uploading entity: 0x%x\r\n", hr);
        return;
    }
}

Esta llamada elimina la entidad y, de hecho, vuelve a la autenticación con clave de telemetría para todos los eventos posteriores.

Actualización de la configuración de la canalización

Las canalizaciones pueden actualizarse fácilmente mediante la API PFEventPipelineUpdateConfiguration, que recibe el identificador de la canalización de eventos existente y una nueva estructura de configuración de la manera siguiente:

void EventPipelineUpdateConfiguration(PFEventPipelineHandle handle)
{
    uint32_t maxEvents = 10;
    uint32_t maxWaitTime = 5;
    uint32_t pollDelay = 50;
    PFHCCompressionLevel compressionLevel = PFHCCompressionLevel::Medium;
    bool retryOnDisconnect = true;
    size_t bufferSize = 2048;

    PFEventPipelineConfig eventPipelineConfig
    {
        &maxEvents,             // maxEventsPerBatch
        &maxWaitTime,           // maxWaitTimeInSeconds
        &pollDelay,             // pollDelayInMs
        &compressionLevel,      // compressionLevel
        &retryOnDisconnect,     // retryOnDisconnect
        &bufferSize,            // bufferSize
    };

    HRESULT hr = PFEventPipelineUpdateConfiguration(
        handle,                 // eventPipelineHandle
        eventPipelineConfig     // eventPipelineConfig
    );

    if (FAILED(hr))
    {
        printf("Failed updating event pipeline configuration: 0x%x\r\n", hr);
        return;
    };
}

Recordatorio: cualquier propiedad vacía o nula sobrescribe el valor de configuración existente con el valor predeterminado.

Claves de telemetría no válidas o desactivadas

En caso de que una clave de telemetría se desactive o se proporcione una clave no válida en la creación de la canalización, cualquier canalización de eventos que se ejecute con esa clave de telemetría empezará a producir errores en cuanto detecte que la clave no es válida o está desactivada. En el caso eventual de que el cliente reactive la clave, la canalización no se dará cuenta de ello y seguirá devolviendo errores a través del controlador de eventos con error. Cabe mencionar que este comportamiento se basa en la sesión, lo que significa que, si se reinicia el título, se crea una nueva canalización que podrá cargar eventos de nuevo.

Ciclo de vida del identificador de la canalización

Al igual que otros identificadores de PlayFab, los identificadores de canalización de eventos usan un patrón de duplicación y cierre:

PFEventPipelineCloseHandle: cierra un identificador de canalización. Cuando se cierra el último identificador de una canalización, la canalización se destruye y se vacían los eventos restantes almacenados en el búfer.
PFEventPipelineDuplicateHandle: duplica un identificador de canalización. Tanto el identificador original como el duplicado deben cerrarse de forma independiente con PFEventPipelineCloseHandle.

// Duplicate a handle for use in another component
PFEventPipelineHandle duplicatedHandle;
HRESULT hr = PFEventPipelineDuplicateHandle(originalHandle, &duplicatedHandle);

// When done, close both handles independently
PFEventPipelineCloseHandle(duplicatedHandle);
PFEventPipelineCloseHandle(originalHandle);

Consulte también

Tutorial de la canalización de eventos

XBOX Services

PlayFab

SDK de PlayFab Services: canalización de eventos

Canalización de eventos

Tipos de canalización

Tipos de autenticación

Autenticación de entidad

Autenticación con clave de telemetría

Configuración de la canalización de eventos

Valores predeterminados

Compresión GZIP

Controladores de eventos

Ejemplos de creación de canalizaciones

Emisión de eventos

Cambio a autenticación de entidad o actualización de la entidad

Cambio a autenticación con clave de telemetría

Actualización de la configuración de la canalización

Claves de telemetría no válidas o desactivadas

Ciclo de vida del identificador de la canalización

Consulte también

​Canalización de eventos

​Tipos de canalización

​Tipos de autenticación

​Autenticación de entidad

​Autenticación con clave de telemetría

​Configuración de la canalización de eventos

​Valores predeterminados

​Compresión GZIP

​Controladores de eventos

​Ejemplos de creación de canalizaciones

​Emisión de eventos

​Cambio a autenticación de entidad o actualización de la entidad

​Cambio a autenticación con clave de telemetría

​Actualización de la configuración de la canalización

​Claves de telemetría no válidas o desactivadas

​Ciclo de vida del identificador de la canalización

​Consulte también

Canalización de eventos

Tipos de canalización

Tipos de autenticación

Autenticación de entidad

Autenticación con clave de telemetría

Configuración de la canalización de eventos

Valores predeterminados

Compresión GZIP

Controladores de eventos

Ejemplos de creación de canalizaciones

Emisión de eventos

Cambio a autenticación de entidad o actualización de la entidad

Cambio a autenticación con clave de telemetría

Actualización de la configuración de la canalización

Claves de telemetría no válidas o desactivadas

Ciclo de vida del identificador de la canalización

Consulte también