SDK PlayFab Services - Event Pipeline - XBOX Game Development Documentation

Event Pipeline est une fonctionnalité du SDK PlayFab Services dont l’objectif principal est de permettre aux développeurs de jeux d’envoyer des événements à stocker dans PlayFab Insights. Elle permet au développeur de spécifier la taille des lots, la fréquence d’envoi et d’autres aspects d’une solution de télémétrie adaptée. Elle allège cette charge pour le développeur de jeux en gérant tous ces aspects à sa place. Les pipelines d’événements sont configurables. Un titre peut contenir un ou plusieurs de ces pipelines, chacun pouvant être configuré avec ses propres propriétés. Passons en revue certains des concepts de base du pipeline.

Types de pipelines

Le type de pipeline est directement lié au type d’événements qu’un pipeline émet. Un développeur peut instancier deux types de pipelines différents :

Telemetry Event Pipeline : ne peut émettre que des événements de télémétrie et utilise l’API REST Write Telemetry Events.
PlayStream Event Pipeline : ne peut émettre que des événements PlayStream et utilise l’API REST Write Events.

Vous pouvez disposer de plusieurs pipelines de types et de configurations différents, mais vous ne pouvez pas modifier le type d’un pipeline après sa création. Pour changer de type, vous devez réinstancier le pipeline.

Types d’authentification

Le type d’authentification est un autre élément important de la création d’un pipeline. Deux mécanismes d’authentification sont pris en charge pour les événements PlayFab : l’authentification par entité et l’authentification par clé de télémétrie. L’authentification par entité est utilisée lorsque le développeur de jeux souhaite lier ses événements à une entité particulière en vue d’une agrégation ou d’une analyse ultérieure. Par exemple, le développeur de jeux peut journaliser des événements liés aux actions des joueurs afin d’analyser plus en détail le comportement des joueurs de votre titre et de permettre une segmentation. L’authentification par clé de télémétrie est utilisée lorsque le développeur de jeux souhaite journaliser des événements qui n’ont pas nécessairement besoin d’être liés à une entité. Par exemple, avant qu’un joueur ne soit connecté, le titre peut commencer à envoyer des événements liés aux performances ou à des métriques spécifiques qu’il souhaite collecter pour une analyse ultérieure. Cela peut se faire sans passer par le processus d’authentification d’entité habituel. Combinaisons type d’authentification / type d’événement prises en charge

	Authentification par entité	Authentification par clé de télémétrie
Événements de télémétrie	Valide	Valide
Événements PlayStream	Valide	Non valide

Authentification par entité

Ce type d’authentification est la méthode d’authentification PlayFab normale et la plus courante. Il est étroitement lié à une entité spécifique et vous oblige à appeler les API de connexion PlayFab correspondantes pour obtenir un jeton d’entité à utiliser dans tous les appels ultérieurs. La liste suivante présente les différents types d’entités utilisables avec l’authentification par entité.

namespace : l’entité d’espace de noms représente l’identité du joueur inter-titres et l’étendue des données partagées. L’ID d’éditeur identifie l’espace de noms.
title : l’entité de titre représente les informations globales propres à ce titre.
master_player_account : le master_player_account est une entité de joueur partagée par tous les titres d’un espace de noms.
title_player_account : pour la plupart des développeurs, title_player_account représente le joueur de la manière la plus traditionnelle.
character : l’entité de personnage est une sous-entité de title_player_account.
group : l’entité de groupe est un conteneur d’autres entités. Elle est actuellement limitée aux joueurs et aux personnages.

Pour plus d’informations sur les différents types d’entités, consultez Types d’entités intégrés. En outre, l’entité du pipeline peut être mise à jour après la création du pipeline en fournissant un PFEntityHandle valide. Le développeur de jeux peut ainsi ajouter une entité pour commencer à y lier ses événements (voir la section Passer à l’authentification par entité ou mettre à jour l’entité), ou même la supprimer s’il souhaite journaliser des éléments qui ne sont pas liés à une entité (voir la section Passer à l’authentification par clé de télémétrie). Si une entité existe sur le pipeline, elle est toujours prioritaire sur l’authentification par clé de télémétrie.

Authentification par clé de télémétrie

L’authentification par clé de télémétrie ne nécessite pas de jeton d’entité ; elle n’est donc liée à aucune entité spécifique. Si l’authentification par clé de télémétrie est utilisée, un struct PFEventPipelineTelemetryKeyConfig est requis lors de la création du pipeline. Ce struct comporte deux éléments principaux :

Une clé de télémétrie, constituée d’une chaîne créée et gérée dans PlayFab Game Manager.
Un PFServiceConfigHandle, qui indique au SDK la configuration de service à utiliser pour l’envoi des événements. Le handle de configuration de service est créé lors de l’initialisation du SDK en appelant PFServiceConfigCreateHandle.

Si le développeur souhaite utiliser une clé de télémétrie, il est important de la fournir lors de la création du pipeline, car il n’existe aucun moyen d’ajouter une clé de télémétrie une fois le pipeline instancié. Notez que l’authentification par clé de télémétrie n’est disponible que pour les événements de télémétrie ; elle ne prend pas en charge les événements PlayStream.

Configuration du pipeline d’événements

Comme indiqué précédemment, le pipeline d’événements possède des propriétés configurables qui peuvent être fournies après la création du pipeline via le paramètre struct PFEventPipelineConfig. Les propriétés configurables sont les suivantes :

maxEventsPerBatch : nombre maximal d’événements regroupés en lot avant leur écriture dans PlayFab.
maxWaitTimeInSeconds : durée maximale pendant laquelle le pipeline attend avant d’envoyer un lot incomplet.
pollDelayInMs : durée pendant laquelle le pipeline attend avant de lire à nouveau la mémoire tampon des événements après l’avoir vidée.
compressionLevel : définit le niveau de compression utilisé par l’algorithme de compression. Pour plus de détails sur la compression, consultez Compression GZIP.
retryOnDisconnect : le pipeline d’événements tente de renvoyer les événements dont l’envoi a échoué en raison d’une perte de connexion. Disponible uniquement pour Telemetry Event Pipeline.
bufferSize : limite du nombre d’événements dans la mémoire tampon du pipeline.

Valeurs par défaut

Propriété	Pipeline de télémétrie	Pipeline PlayStream
maxEventsPerBatch	5	5
maxWaitTimeInSeconds	3	3
pollDelayInMs	3000	10
compressionLevel	None (désactivé)	None (désactivé)
retryOnDisconnect	true	N/A
bufferSize	1024	1024

Si seules certaines propriétés de PFEventPipelineConfig sont spécifiées, les propriétés vides sont remplacées et utilisent les valeurs par défaut. Pour un exemple de mise à jour de l’une de ces propriétés pour le pipeline d’événements, consultez Mettre à jour la configuration du pipeline.

Compression GZIP

Le pipeline d’événements offre la possibilité de compresser les charges utiles du corps à l’aide de la norme de compression GZIP. Le niveau de compression souhaité peut être spécifié dans le struct PFEventPipelineConfig, qui fait partie des paramètres de l’API PFEventPipelineUpdateConfiguration. Un niveau de compression plus faible compresse moins mais offre la vitesse la plus élevée, tandis qu’un niveau de compression plus élevé permet d’obtenir de meilleurs taux de compression, au prix d’une vitesse de compression plus lente. La différence entre les taux de compression dépend entièrement du type de données envoyées. Selon la taille et le caractère aléatoire des données, les taux de compression peuvent être identiques même avec des niveaux différents. Compromis : L’utilisation de la compression augmente le temps processeur en raison de la complexité supplémentaire liée à l’exécution d’un algorithme de compression, mais la charge utile réseau du corps diminue considérablement. Il appartient donc au développeur de jeux de décider s’il convient d’utiliser la compression, en fonction des besoins et des ressources du jeu. D’après une validation interne, on observe en moyenne une augmentation de 20 % du temps processeur et une diminution de 91 % de la taille de la charge utile du corps. Ces pourcentages peuvent varier considérablement en fonction de la taille de la charge utile et de la complexité des données compressées.

Gestionnaires d’événements

Lors de la création du pipeline, les développeurs de jeux peuvent fournir deux gestionnaires d’événements facultatifs, appelés lors de l’envoi des événements. Toutefois, si le développeur de jeux souhaite un fonctionnement de type “fire and forget” (envoyer et oublier), il peut omettre les gestionnaires d’événements. Les gestionnaires d’événements pouvant être fournis sont les suivants :

PFEventPipelineBatchUploadSucceededEventHandler : comme son nom l’indique, il reçoit tous les événements envoyés avec succès à PlayFab.
PFEventPipelineBatchUploadFailedEventHandler : il reçoit tous les événements ayant échoué après application de la logique de nouvelle tentative du pipeline.

Exemples de création de pipelines

Vous trouverez ci-dessous différents exemples d’instanciation d’un pipeline d’événements, basés sur les sujets abordés précédemment.

Création d’un Telemetry Event Pipeline avec authentification par entité Si le développeur souhaite envoyer des événements de télémétrie sans avoir besoin de l’authentification par clé de télémétrie, l’API PFEventPipelineCreateTelemetryPipelineHandleWithEntity répond à ce besoin, comme le montre l’exemple suivant :

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

Cet exemple montre comment créer un Telemetry Event Pipeline qui utilise l’authentification par entité et ne possède aucun gestionnaire. Le pipeline envoie donc les événements sans se préoccuper du résultat.

Création d’un Telemetry Event Pipeline avec authentification par clé de télémétrie Si le développeur souhaite envoyer des événements de télémétrie et a besoin de l’authentification par clé de télémétrie, l’API PFEventPipelineCreateTelemetryPipelineHandleWithKey répond à ce besoin, comme le montre l’exemple suivant :

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

Cet exemple montre comment créer un pipeline d’événements de télémétrie qui n’utilise pas l’authentification par entité. Le pipeline d’événements commence à envoyer des événements à l’aide de la clé de télémétrie, avec la possibilité d’ajouter une entité ultérieurement. Voir Passer à l’authentification par entité ou mettre à jour l’entité

Création d’un PlayStream Event Pipeline Si le développeur souhaite envoyer des événements PlayStream, l’API PFEventPipelineCreatePlayStreamPipelineHandle répond à ce besoin, comme le montre l’exemple suivant :

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

Cet exemple montre comment créer un PlayStream Event Pipeline qui utilise l’authentification par entité et ne possède aucun gestionnaire. Le pipeline envoie donc les événements sans se préoccuper du résultat.

Pipeline d’événements utilisant des gestionnaires d’événements Cet exemple montre comment fournir des gestionnaires d’événements aux API de création de pipelines.

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

Comme le montre l’exemple, OnBatchUploadedHandler et OnBatchUploadFailedHandler sont déclarées comme deux fonctions de rappel distinctes, transmises lors de la création du pipeline d’événements. Chaque résultat associé à un événement est renvoyé dans l’une de ces deux fonctions, selon que le résultat est une réussite ou un échec. Il appartient au développeur de jeux de décider comment gérer le résultat.

Émettre des événements

L’émission d’événements est une opération simple une fois le pipeline d’événements créé. Le développeur de jeux doit appeler l’API PFEventPipelineEmitEvent, qui reçoit le handle du pipeline d’événements existant et l’événement à envoyer.

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

Il est important de noter que lors de l’utilisation de l’authentification par clé de télémétrie, la seule valeur valide pour entityType dans PFEntityKey est “external”. Tous les autres types d’entités sont rejetés et les événements ne sont pas envoyés. Exemple de PFEntityKey valide lors de l’utilisation de l’authentification par clé de télémétrie :

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 la limite de taille de la mémoire tampon est dépassée lors de l’émission d’un événement, le SDK renvoie l’erreur suivante :

E_PF_API_CLIENT_REQUEST_RATE_LIMIT_EXCEEDED (0x892354dd)

Veillez à définir une taille de mémoire tampon adaptée à vos besoins.

Passer à l’authentification par entité ou mettre à jour l’entité

Si un pipeline a été créé uniquement avec une configuration de clé de télémétrie, il est possible de passer à l’authentification par entité, ou de mettre à jour votre pipeline pour qu’il utilise une autre entité. À l’aide de PFEventPipelineAddUploadingEntity, il est possible d’associer une entité à un pipeline en cours d’exécution sans avoir à le réinitialiser. Cette fonction remplace également l’entité existante, le cas échéant. Exemple : Un Telemetry Event Pipeline est créé avec une configuration de clé de télémétrie au début de l’exécution du titre. Cela peut être dû au fait qu’il n’existe pas encore d’identité de joueur, ou que vous ne souhaitez pas encore journaliser d’éléments liés à un joueur.

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

Une fois qu’un joueur s’est connecté, ou lorsque vous souhaitez commencer à envoyer des événements associés à une entité particulière, appelez PFEventPipelineAddUploadingEntity avec le handle du pipeline d’événements existant et le handle de l’entité souhaitée, comme suit :

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

Après cet appel, le pipeline commence à journaliser tous les événements suivants en les liant à cette entité.

Passer à l’authentification par clé de télémétrie

Pour compléter le scénario précédent, si le développeur souhaite revenir à l’authentification par télémétrie et dissocier la journalisation des événements de l’entité, il peut appeler PFEventPipelineRemoveUploadingEntity en transmettant le handle du pipeline d’événements, comme suit :

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

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

Cet appel supprime l’entité et rétablit effectivement l’authentification par clé de télémétrie pour tous les événements suivants.

Mettre à jour la configuration du pipeline

Vous pouvez mettre à jour les pipelines à l’aide de l’API PFEventPipelineUpdateConfiguration, qui reçoit le handle du pipeline d’événements existant et un nouveau struct de configuration, comme suit :

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

Rappel : toute propriété vide ou null remplace la valeur de configuration existante par la valeur par défaut.

Clés de télémétrie non valides ou désactivées

Si une clé de télémétrie est désactivée, ou si une clé non valide est fournie lors de la création du pipeline, tous les pipelines d’événements utilisant cette clé de télémétrie commencent à échouer dès qu’ils détectent que la clé n’est pas valide ou qu’elle est désactivée. Si le client réactive ensuite la clé, le pipeline ne s’en rend pas compte et continue de renvoyer des échecs via le gestionnaire d’événements d’échec. Notez que ce comportement est lié à la session : si le titre est redémarré, un nouveau pipeline est créé et peut à nouveau envoyer des événements.

Cycle de vie des handles de pipeline

Comme les autres handles PlayFab, les handles de pipeline d’événements utilisent un modèle de duplication/fermeture :

PFEventPipelineCloseHandle : ferme un handle de pipeline. Lorsque le dernier handle d’un pipeline est fermé, le pipeline est détruit et tous les événements restants dans la mémoire tampon sont vidés.
PFEventPipelineDuplicateHandle : duplique un handle de pipeline. Le handle d’origine et le handle dupliqué doivent tous deux être fermés indépendamment avec 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);

Voir aussi

Tutoriel Event Pipeline

​Types de pipelines

​Types d’authentification

​Authentification par entité

​Authentification par clé de télémétrie

​Configuration du pipeline d’événements

​Valeurs par défaut

​Compression GZIP

​Gestionnaires d’événements

​Exemples de création de pipelines

​Émettre des événements

​Passer à l’authentification par entité ou mettre à jour l’entité

​Passer à l’authentification par clé de télémétrie

​Mettre à jour la configuration du pipeline

​Clés de télémétrie non valides ou désactivées

​Cycle de vie des handles de pipeline

​Voir aussi