Tutorial de la canalización de eventos - XBOX Game Development Documentation

Este documento es un breve tutorial paso a paso sobre cómo usar la característica de canalización de eventos en el SDK de PlayFab Services.

Paso 1: Inicializar el SDK de PlayFab Services

El primer paso es inicializar el SDK de PlayFab Services mediante las API PFServicesInitialize y PFServiceConfigCreateHandle. La API PFServiceConfigCreateHandle recibe una cadena de conexión y un identificador de título que pueden obtenerse desde su título en PlayFab Game Manager. El tercer parámetro es una estructura PFServiceConfigHandle que representa la configuración que se está creando. Este identificador de configuración de servicio se usará en el paso siguiente.

PFServiceConfigHandle serviceConfigHandle;

PFServicesInitialize(nullptr);

PFServiceConfigCreateHandle(
    "titleConnectionString",
    "titleId",
    &serviceConfigHandle
);

Paso 2: Crear una canalización de eventos de telemetría

A continuación, creemos una canalización de eventos de telemetría con una clave de telemetría mediante la API PFEventPipelineCreateTelemetryPipelineHandleWithKey. Las claves de telemetría se crean y administran a través de PlayFab Game Manager. Al crear la estructura PFEventPipelineTelemetryKeyConfig, pasamos la clave de telemetría real y el identificador de configuración de servicio que obtuvimos durante la inicialización del SDK.

PFEventPipelineHandle handle;
XTaskQueueHandle taskQueueHandle;

XTaskQueueCreate(XTaskQueueDispatchMode::ThreadPool, XTaskQueueDispatchMode::Manual, &taskQueueHandle);

PFEventPipelineTelemetryKeyConfig telemetryKeyConfig
{
    "myTelemetryKey",
    serviceConfigHandle,
};

HRESULT hr = PFEventPipelineCreateTelemetryPipelineHandleWithKey(
    &telemetryKeyConfig,
    taskQueueHandle,
    nullptr,
    nullptr,
    nullptr,
    &handle
);

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

Paso 3: Actualizar la configuración de la canalización

Actualicemos la configuración de la canalización; en este ejemplo queremos enviar lotes de un máximo de 10 eventos (el valor predeterminado es 5). Además, como estamos enviando maxWaitTimeInSeconds y pollDelayInMs como punteros nulos, usan el valor predeterminado para el tipo de canalización respectivo. También estamos especificando un nivel de compresión “Medium”; establecer esta propiedad comprime las cargas del cuerpo y ayuda a optimizar la utilización de los recursos de red. Después llamamos a PFEventPipelineUpdateConfiguration pasando el PFEventPipelineHandle que obtuvimos en el paso anterior y la estructura PFEventPipelineConfig.

uint32_t maxEvents = 10;
PFHCCompressionLevel compressionLevel = PFHCCompressionLevel::Medium;

PFEventPipelineConfig eventPipelineConfig
{
    &maxEvents,         // maxEventsPerBatch
    nullptr,            // maxWaitTimeInSeconds
    nullptr,            // pollDelayInMs
    &compressionLevel   // compressionLevel
};

HRESULT hr = PFEventPipelineUpdateConfiguration(
    handle,
    eventPipelineConfig
);

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

Paso 4: Emitir un evento

En este paso, procedemos a emitir solo 1 evento con el nombre “TelemetryKeyEvent” a través de la API PFEventPipelineEmitEvent. Este evento no está vinculado a ninguna entidad, ya que hasta ahora no hemos proporcionado autenticación de entidad.

PFEvent myEvent
{
    nullptr,
    "custom.playfab.events.PlayFab.Test.TelemetryEventPipelineTests",
    "TelemetryKeyEvent",
    nullptr,
    "{}"
};

HRESULT hr = PFEventPipelineEmitEvent(
    handle,
    &myEvent
);

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

Paso 5: Obtener una entidad

Aquí queremos obtener una entidad que podamos usar para empezar a vincularla con nuestros eventos. Para este tutorial, llamamos a la API PFAuthenticationReLoginWithXUserAsync para obtener un PFEntityHandle válido.

El objeto userHandle que se pasa como parte de PFAuthenticationLoginWithXUserRequest es de tipo XUserHandle. Los pasos para obtener un XUserHandle válido quedan fuera del ámbito de este tutorial. Para obtener más información sobre este tema, consulte la documentación de XUserAddAsync.

PFEntityHandle entityHandle;

PFAuthenticationLoginWithXUserRequest request{};
request.createAccount = true;
request.user = userHandle; // An XUserHandle obtained from XUserAddAsync

XAsyncBlock async{};

HRESULT hr = PFAuthenticationReLoginWithXUserAsync(entityHandle, &request, &async);

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

hr = XAsyncGetStatus(&async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage

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

Paso 6: Agregar la entidad a la canalización

Como ya tenemos una entidad válida, podemos llamar a PFEventPipelineAddUploadingEntity y pasar el identificador de la canalización de eventos y el identificador de entidad del paso anterior. Esta acción permite que la canalización cambie a usar la autenticación de entidad.

HRESULT hr = PFEventPipelineAddUploadingEntity(
    handle,
    entityHandle
);

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

Paso 7: Emitir un evento

Este procedimiento es el mismo que el envío de eventos anterior. Las únicas dos diferencias son:

Etiquetamos este evento con un nombre diferente (“EntityEvent”) para que quede más claro.
Este evento se registra y se vincula con la entidad que obtuvimos anteriormente.

PFEvent myEvent
{
    nullptr,
    "custom.playfab.events.PlayFab.Test.TelemetryEventPipelineTests",
    "EntityEvent",
    nullptr,
    "{}"
};

hr = PFEventPipelineEmitEvent(
    handle,
    &myEvent
);

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

Paso 8: Cerrar el identificador de la canalización de eventos

Por último, cuando hayamos terminado de cargar eventos, lo único que tenemos que hacer es llamar a PFEventPipelineCloseHandle pasando nuestro identificador de canalización.

PFEventPipelineCloseHandle(handle);

Consulte también

Información general sobre la canalización de eventos

​Paso 1: Inicializar el SDK de PlayFab Services

​Paso 2: Crear una canalización de eventos de telemetría

​Paso 3: Actualizar la configuración de la canalización

​Paso 4: Emitir un evento

​Paso 5: Obtener una entidad

​Paso 6: Agregar la entidad a la canalización

​Paso 7: Emitir un evento

​Paso 8: Cerrar el identificador de la canalización de eventos

​Consulte también

Paso 1: Inicializar el SDK de PlayFab Services

Paso 2: Crear una canalización de eventos de telemetría

Paso 3: Actualizar la configuración de la canalización

Paso 4: Emitir un evento

Paso 5: Obtener una entidad

Paso 6: Agregar la entidad a la canalización

Paso 7: Emitir un evento

Paso 8: Cerrar el identificador de la canalización de eventos

Consulte también