Migrer du SDK autonome PlayFab v1 vers le SDK unifié v2

​

Vue d’ensemble des modifications

• Architecture unifiée : tous les services PlayFab (Core, Services, Party, Multiplayer, GameSave) sont intégrés dans un seul SDK
• Authentification simplifiée : une seule connexion donne accès à tous les services PlayFab via des handles d’entité
• Gestion automatique des jetons : plus besoin d’actualiser manuellement les jetons ni de gérer les ID d’entité
• Interopérabilité améliorée : communication fluide entre les différents services PlayFab
• Structure de projet simplifiée : une seule installation de SDK au lieu de plusieurs packages distincts

​

Modifications de la structure du projet

​

Pour les utilisateurs du GDK

• Extensions distinctes pour chaque composant du SDK
• Dossiers d’inclusion et de bibliothèques individuels : PlayFab.Services.Cpp, PlayFab.Party.Cpp, PlayFab.Multiplayer.Cpp
• Chaque service avait un nom ExtensionLibrary distinct dans le GDK
• Plusieurs téléchargements requis depuis GitHub pour les différents services PlayFab

• Un seul SDK PlayFab unifié
• Structure organisée par plateforme avec des sous-dossiers (xbox, windows, etc.)
• Tous les en-têtes regroupés dans un seul dossier includes (Core, Services, Multiplayer, Party, GameSave)
• Bibliothèques combinées dans un dossier lib unifié

​

Mise à jour des références de votre projet

1. Supprimez les anciennes références : supprimez les références à PlayFab.Services.Cpp, PlayFab.Party.Cpp et aux autres extensions de SDK individuelles
2. Ajoutez la référence unifiée : référencez le nouveau SDK unifié PlayFab ou mettez à jour les chemins d’inclusion et de bibliothèques vers les emplacements unifiés
3. Anticipez l’avenir : Microsoft supprimera les anciens dossiers dans les futures versions du GDK (éventuellement d’ici 2026) ; mettez donc à jour vos fichiers de projet en conséquence

​

Pour les utilisateurs de GitHub/autonomes

• Remplacez les multiples téléchargements de SDK par le package SDK unifié unique
• Mettez à jour les chemins du projet pour utiliser la nouvelle structure de dossiers organisée par plateforme

​

Authentification et gestion des entités

​

Modifications de la gestion des jetons

• Récupération manuelle des jetons à l’aide de PFAuthenticationGetEntityTokenAsync
• Actualisation manuelle des jetons à leur expiration
• Transmission de l’ID d’entité et des chaînes de jeton aux autres services (par exemple, partyManager.CreateLocalUser(entityId, titlePlayerEntityToken, &localUser))

• Gestion automatique des jetons par le SDK Core
• Actualisation des jetons en arrière-plan avant leur expiration
• Transmission directe du PFEntityHandle aux autres services (par exemple, partyManager.CreateLocalUser(entityHandle, &localUser))

​

Étapes de migration pour l’authentification

1. Supprimez la gestion manuelle des jetons : supprimez le code qui récupère ou vérifie manuellement les jetons PlayFab
2. Stockez les handles d’entité : conservez le PFEntityHandle obtenu lors de la connexion et utilisez-le dans tous les services PlayFab
3. Mettez à jour les appels de service : remplacez les paramètres d’ID d’entité et de jeton par des handles d’entité
4. Gérez la réauthentification : utilisez les API PFAuthenticationReLogin*Async pour les scénarios de réauthentification

​

Modifications d’API incompatibles par composant

​

PlayFab Core

• La plupart des appels au service Core restent inchangés
• Mettez à jour les chemins d’inclusion pour qu’ils pointent vers les en-têtes du SDK unifié

​

PlayFab Services

• La plupart des appels Services restent inchangés
• Mettez à jour les chemins d’inclusion pour qu’ils pointent vers les en-têtes du SDK unifié

​

PlayFab Party (mise en réseau/voix)

​

Modifications de l’initialisation

PartyManager& partyManager = PartyManager::GetSingleton();
PartyError err = partyManager.Initialize("YOUR_PLAYFAB_TITLE_ID");

PartyManager& partyManager = PartyManager::GetSingleton();

PartyInitializationConfiguration partyInitConfig = {};
partyInitConfig.titleId = "YOUR_PLAYFAB_TITLE_ID";
partyInitConfig.audioTaskQueue = nullptr;
partyInitConfig.networkingTaskQueue = nullptr;

PartyError err = partyManager.Initialize(&partyInitConfig);

​

Modifications de la création d’utilisateurs locaux

PartyLocalUser* localUser = nullptr;
PartyError err = partyManager.CreateLocalUser(entityId, titlePlayerEntityToken, &localUser);

PartyLocalUser* localUser = nullptr;
PartyError err = partyManager.CreateLocalUser(entityHandle, &localUser);

​

Étapes de migration pour Party

1. Mettez à jour l’initialisation : remplacez le simple appel PartyManager::Initialize() par l’approche utilisant une structure de configuration
2. Supprimez la récupération des jetons : supprimez tout code qui obtient manuellement l’ID d’entité et le jeton pour Party
3. Transmettez des handles d’entité : utilisez directement PFEntityHandle au lieu de paramètres de type chaîne
4. Supprimez la logique d’actualisation des jetons : supprimez le code qui vérifie ou actualise périodiquement les jetons Party
5. Mettez à jour les dépendances : assurez-vous que PlayFab Core est initialisé avant PartyManager::Initialize()
6. Supprimez les appels propres à XBOX : remplacez PartyXblManagerInitialize() par l’appel générique PartyInitialize() sur XBOX

​

PlayFab Multiplayer (Lobby et matchmaking)

​

Modifications des opérations de lobby

PFEntityKey newMember{ entityId, entityType };
HRESULT hr = PFMultiplayerJoinLobby(pfmHandle, &newMember, connectionString, &joinConfig, nullptr, &lobby);

HRESULT hr = PFMultiplayerJoinLobbyWithEntityHandle(pfmHandle, entityHandle, connectionString, &joinConfig, nullptr, &lobby);

​

Étapes de migration pour Multiplayer

1. Mettez à jour les appels de fonction : remplacez les paramètres d’ID PlayFab et de jeton d’entité par PFEntityHandle
2. Supprimez les étapes d’authentification : supprimez les appels distincts « Authenticate Multiplayer »
3. Initialisez explicitement : appelez PFMultiplayerInitialize() et éventuellement PFMultiplayerStartProcessing()
4. Mettez à jour le matchmaking : utilisez des handles d’entité lors de la création des tickets de matchmaking

​

Liste de vérification générale de la migration

​

Mises à jour du code

• Mettre à jour les chemins d’inclusion : pointez vers le répertoire d’inclusion du SDK unifié
• Mettre à jour l’édition des liens des bibliothèques : liez les bibliothèques unifiées au lieu des bibliothèques distinctes
• Supprimer les fonctions dépréciées : supprimez les appels aux fonctions supprimées, comme PartyManager::CreateLocalUserWithEntityType
• Remplacer la gestion manuelle des jetons : supprimez la logique de mise en cache et d’actualisation des jetons
• Mettre à jour l’ordre d’initialisation : assurez-vous que PlayFab Core est initialisé avant les autres services

​

Liste de vérification des tests

• Authentification : la connexion renvoie un handle d’entité valide
• Opérations de lobby : la création et la jonction de lobbies fonctionnent correctement
• Mise en réseau Party : les joueurs peuvent se connecter et communiquer entre différentes machines
• Gestion des erreurs : tous les appels PlayFab gèrent correctement les erreurs
• Scénarios multi-utilisateurs : plusieurs utilisateurs locaux fonctionnent, le cas échéant

​

Problèmes courants et solutions

• Vérifiez si les signatures de fonction ont changé pour exiger un PFEntityHandle
• Assurez-vous de transmettre le handle d’entité au lieu d’ID sous forme de chaînes

• Vérifiez que PlayFab Core est initialisé avant les autres services
• Vérifiez que la connexion est terminée avant de créer des utilisateurs locaux dans Party/Multiplayer

• Rares, mais vérifiez que la v2 n’introduit pas de problèmes dans les chemins de code critiques en termes de performances

​

Avantages de la migration

​

Simplification du code

• Complexité réduite : supprimez le code de contournement lié à la séparation des services de la v1
• Gestion unifiée des erreurs : tous les services PlayFab utilisent un signalement des erreurs cohérent
• Authentification centralisée : un seul flux de connexion pour toutes les fonctionnalités PlayFab

​

Interopérabilité améliorée

• Intégration fluide : l’ajout de nouvelles fonctionnalités PlayFab nécessite une configuration minimale
• Meilleure prise en charge multi-utilisateurs : le SDK unifié gère plus efficacement plusieurs utilisateurs locaux
• Modèle d’entité cohérent : même approche d’authentification pour tous les services

​

Pérennité

• Développement actif : la v2 est la version activement maintenue
• Nouvelles fonctionnalités : les futures fonctionnalités PlayFab cibleront le SDK unifié
• Support à long terme : les SDK v1 finiront par être dépréciés

​

Étapes suivantes

1. Mettez à jour la structure du projet : migrez vers la structure du SDK unifié
2. Refactorisez l’authentification : implémentez l’approche basée sur les handles d’entité
3. Testez minutieusement : vérifiez que toutes les fonctionnalités PlayFab fonctionnent correctement
4. Nettoyez le code : supprimez les contournements v1 dépréciés et la gestion manuelle des jetons
5. Surveillez les performances : assurez-vous que la migration n’introduit pas de problèmes de performances