Tutoriel Event Pipeline - XBOX Game Development Documentation

Ce document est un tutoriel rapide, étape par étape, sur l’utilisation de la fonctionnalité Event Pipeline du SDK PlayFab Services.

Étape 1 : initialiser le SDK PlayFab Services

La première étape consiste à initialiser le SDK PF Service à l’aide des API PFServicesInitialize et PFServiceConfigCreateHandle. L’API PFServiceConfigCreateHandle reçoit une chaîne de connexion et un ID de titre, que vous pouvez obtenir à partir de votre titre dans PlayFab Game Manager. Le troisième paramètre est un struct PFServiceConfigHandle qui représente la configuration en cours de création. Ce handle de configuration de service sera utilisé à l’étape suivante.

PFServiceConfigHandle serviceConfigHandle;

PFServicesInitialize(nullptr);

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

Étape 2 : créer un pipeline d’événements de télémétrie

Créons ensuite un pipeline d’événements de télémétrie avec une clé de télémétrie à l’aide de l’API PFEventPipelineCreateTelemetryPipelineHandleWithKey. Les clés de télémétrie sont créées et gérées dans PlayFab Game Manager. Lors de la création du struct PFEventPipelineTelemetryKeyConfig, nous transmettons la clé de télémétrie proprement dite ainsi que le handle de configuration de service obtenu lors de l’initialisation du 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;
}

Étape 3 : mettre à jour la configuration du pipeline

Mettons à jour la configuration du pipeline : dans cet exemple, nous voulons envoyer des lots de 10 événements au maximum (la valeur par défaut est 5). En outre, comme nous transmettons maxWaitTimeInSeconds et pollDelayInMs sous forme de pointeurs null, ils utilisent la valeur par défaut du type de pipeline concerné. Nous spécifions également un niveau de compression “Medium” : la définition de cette propriété compresse les charges utiles du corps et permet d’optimiser l’utilisation des ressources réseau. Nous appelons ensuite PFEventPipelineUpdateConfiguration en transmettant le PFEventPipelineHandle obtenu à l’étape précédente et le 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;
};

Étape 4 : émettre un événement

Dans cette étape, nous émettons un seul événement nommé “TelemetryKeyEvent” à l’aide de l’API PFEventPipelineEmitEvent. Cet événement n’est lié à aucune entité, car nous n’avons pas encore fourni d’authentification d’entité.

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

Étape 5 : obtenir une entité

Nous voulons ici obtenir une entité que nous pourrons commencer à lier à nos événements. Dans ce tutoriel, nous appelons l’API PFAuthenticationReLoginWithXUserAsync pour obtenir un PFEntityHandle valide.

L’objet userHandle transmis dans le cadre de PFAuthenticationLoginWithXUserRequest est de type XUserHandle. Les étapes permettant d’obtenir un XUserHandle valide sortent du cadre de ce tutoriel. Pour plus d’informations à ce sujet, consultez la documentation 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;
}

Étape 6 : ajouter l’entité au pipeline

Comme nous disposons désormais d’une entité valide, nous pouvons appeler PFEventPipelineAddUploadingEntity en transmettant le handle du pipeline d’événements et le handle d’entité de l’étape précédente. Cette action permet au pipeline de passer à l’authentification par entité.

HRESULT hr = PFEventPipelineAddUploadingEntity(
    handle,
    entityHandle
);

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

Étape 7 : émettre un événement

Cette procédure est identique à l’envoi d’événement précédent. Les deux seules différences sont les suivantes :

Nous attribuons à cet événement un nom différent (“EntityEvent”) pour plus de clarté.
Cet événement est journalisé et lié à l’entité que nous avons obtenue précédemment.

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

Étape 8 : fermer le handle du pipeline d’événements

Enfin, une fois l’envoi des événements terminé, il suffit d’appeler PFEventPipelineCloseHandle en transmettant notre handle de pipeline.

PFEventPipelineCloseHandle(handle);

Voir aussi

Vue d’ensemble d’Event Pipeline

​Étape 1 : initialiser le SDK PlayFab Services

​Étape 2 : créer un pipeline d’événements de télémétrie

​Étape 3 : mettre à jour la configuration du pipeline

​Étape 4 : émettre un événement

​Étape 5 : obtenir une entité

​Étape 6 : ajouter l’entité au pipeline

​Étape 7 : émettre un événement

​Étape 8 : fermer le handle du pipeline d’événements

​Voir aussi

Étape 1 : initialiser le SDK PlayFab Services

Étape 2 : créer un pipeline d’événements de télémétrie

Étape 3 : mettre à jour la configuration du pipeline

Étape 4 : émettre un événement

Étape 5 : obtenir une entité

Étape 6 : ajouter l’entité au pipeline

Étape 7 : émettre un événement

Étape 8 : fermer le handle du pipeline d’événements

Voir aussi