Tutorial do Event Pipeline - XBOX Game Development Documentation

Este documento é um tutorial rápido e passo a passo sobre como usar o recurso Event Pipeline no SDK do PlayFab Services.

Etapa 1 - Inicializar o SDK do PlayFab Services

A primeira etapa é inicializar o SDK do PF Service usando as APIs PFServicesInitialize e PFServiceConfigCreateHandle. A API PFServiceConfigCreateHandle recebe uma cadeia de conexão e uma ID de título, que podem ser obtidas do seu título no PlayFab Game Manager. O terceiro parâmetro é um struct PFServiceConfigHandle que representa a configuração que está sendo criada. Esse identificador de configuração de serviço será usado na próxima etapa.

PFServiceConfigHandle serviceConfigHandle;

PFServicesInitialize(nullptr);

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

Etapa 2 - Criar o pipeline de eventos de telemetria

Em seguida, vamos criar um pipeline de eventos de telemetria com uma chave de telemetria usando a API PFEventPipelineCreateTelemetryPipelineHandleWithKey. As chaves de telemetria são criadas e gerenciadas pelo PlayFab Game Manager. Ao criar o struct PFEventPipelineTelemetryKeyConfig, passamos a chave de telemetria real e o identificador de configuração de serviço obtido durante a inicialização do 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;
}

Etapa 3 - Atualizar a configuração do pipeline

Vamos atualizar a configuração do pipeline. Neste exemplo, queremos enviar lotes de no máximo 10 eventos (o padrão é 5). Além disso, como estamos enviando maxWaitTimeInSeconds e pollDelayInMs como ponteiros nulos, eles usam o valor padrão do respectivo tipo de pipeline. Também estamos especificando um nível de compactação “Medium”. Definir essa propriedade compacta os payloads do corpo e ajuda a otimizar o uso dos recursos de rede. Em seguida, chamamos PFEventPipelineUpdateConfiguration, passando o PFEventPipelineHandle obtido na etapa anterior e o struct 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;
};

Etapa 4 - Emitir um evento

Nesta etapa, emitimos apenas 1 evento com o nome “TelemetryKeyEvent” por meio da API PFEventPipelineEmitEvent. Este evento não está vinculado a nenhuma entidade, pois até agora não fornecemos autenticação de entidade.

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;
}

Etapa 5 - Obter uma entidade

Aqui, queremos obter uma entidade que possamos começar a vincular aos nossos eventos. Neste tutorial, estamos chamando a API PFAuthenticationReLoginWithXUserAsync para obter um PFEntityHandle válido.

O objeto userHandle passado como parte de PFAuthenticationLoginWithXUserRequest é do tipo XUserHandle. As etapas para obter um XUserHandle válido estão fora do escopo deste tutorial. Para obter mais informações sobre esse assunto, consulte a documentação 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;
}

Etapa 6 - Adicionar a entidade ao pipeline

Como já obtivemos uma entidade válida, podemos chamar PFEventPipelineAddUploadingEntity e passar o identificador do pipeline de eventos e o identificador de entidade da etapa anterior. Essa ação permite que o pipeline passe a usar a autenticação de entidade.

HRESULT hr = PFEventPipelineAddUploadingEntity(
    handle,
    entityHandle
);

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

Etapa 7 - Emitir um evento

Este procedimento é igual ao do envio de evento anterior. As únicas duas diferenças são:

Estamos marcando este evento com um nome diferente (“EntityEvent”) para deixar mais claro.
Este evento é registrado e vinculado à entidade que obtivemos 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;
}

Etapa 8 - Fechar o identificador do pipeline de eventos

Por fim, quando terminarmos de carregar os eventos, a única coisa que precisamos fazer é chamar PFEventPipelineCloseHandle, passando nosso identificador de pipeline.

PFEventPipelineCloseHandle(handle);

Confira também

Visão geral do Event Pipeline

​Etapa 1 - Inicializar o SDK do PlayFab Services

​Etapa 2 - Criar o pipeline de eventos de telemetria

​Etapa 3 - Atualizar a configuração do pipeline

​Etapa 4 - Emitir um evento

​Etapa 5 - Obter uma entidade

​Etapa 6 - Adicionar a entidade ao pipeline

​Etapa 7 - Emitir um evento

​Etapa 8 - Fechar o identificador do pipeline de eventos

​Confira também

Etapa 1 - Inicializar o SDK do PlayFab Services

Etapa 2 - Criar o pipeline de eventos de telemetria

Etapa 3 - Atualizar a configuração do pipeline

Etapa 4 - Emitir um evento

Etapa 5 - Obter uma entidade

Etapa 6 - Adicionar a entidade ao pipeline

Etapa 7 - Emitir um evento

Etapa 8 - Fechar o identificador do pipeline de eventos

Confira também