Guide d'implémentation de PlayFab Game Saves sur Steam Deck

​

Vue d’ensemble

​

Différences de comportement du moteur de synchronisation

• Synchronisez fréquemment les données de sauvegarde (par exemple, après chaque niveau, point de contrôle ou progression importante)
• Synchronisez toujours avant d’afficher une confirmation de « quitter le jeu »
• Envisagez une synchronisation en arrière-plan lors des transitions de jeu
• Implémentez des indicateurs de progression de la synchronisation pour garantir qu’elle se termine avant l’arrêt
• C’est particulièrement important pour les appareils portables, sur lesquels l’épuisement de la batterie ou les arrêts soudains sont fréquents

​

Prérequis

1. D’avoir terminé la configuration du GDK d’octobre 2025 : suivez le guide d’implémentation avec le GDK d’octobre 2025
2. D’avoir intégré l’API Steam : initialisation de base de l’API Steam et détection du Steam Deck
3. D’avoir choisi une approche d’intégration : choisissez entre l’intégration à l’écosystème XBOX et l’intégration d’une identité personnalisée (voir ci-dessous)
4. De disposer de toutes les DLL requises : les DLL du SDK unifié doivent être déployées avec votre build Steam

​

Approches d’implémentation

​

Approche 1 : intégration à l’écosystème XBOX (recommandée)

• Synchronisation multiplateforme complète : les données de sauvegarde se synchronisent entre le Steam Deck, les consoles XBOX, le PC Microsoft Store et les autres plateformes compatibles XBOX
• Intégration XBOX Live : les joueurs utilisent leur gamertag XBOX et peuvent accéder aux fonctionnalités sociales XBOX
• Identité de joueur unifiée : le même profil de joueur sur toutes les plateformes
• Authentification éprouvée : tire parti de l’infrastructure d’authentification mature de XBOX Live
• Compatibilité XBOX Game Studios : intégration transparente pour les studios first-party et partenaires XBOX

• Authentification complexe : des gestionnaires d’événements XUser et des rappels d’interface utilisateur personnalisés sont requis
• Configuration d’un bac à sable de développement : requise pour les environnements de test autres que de production
• Privilèges d’administrateur : requis pour les modifications du Registre lors de la configuration du bac à sable
• Implémentation d’une interface utilisateur supplémentaire : authentification par code QR et boîtes de dialogue de sélection du gamertag

​

Approche 2 : implémentation d’une identité personnalisée (alternative)

• Complexité de connexion potentiellement réduite : aucune authentification d’utilisateur XBOX requise
• Aucune configuration du Registre : aucune configuration de bac à sable nécessaire
• Aucune API XUser : élimine les gestionnaires d’événements complexes
• Flexibilité de l’identité personnalisée : implémentez votre propre système d’identité de joueur multiplateforme

• Gestion manuelle des joueurs : vous devez implémenter votre propre système d’identité de joueur multiplateforme
• Intégration limitée à l’écosystème : aucun accès aux fonctionnalités sociales XBOX Live ni à la base de joueurs XBOX existante
• Passerelles entre plateformes : nécessite des solutions personnalisées pour relier les joueurs des différentes plateformes
• Infrastructure d’identité supplémentaire : vous devez créer ou intégrer des systèmes d’identité tiers

​

Configuration commune (les deux approches)

​

1. Exigences de déploiement des DLL

• libHttpClient.dll : opérations HTTP
• PlayFabCore.dll : authentification et services principaux
• PlayFabGameSave.dll : fonctionnalités de Game Saves
• xgameruntime.dll : fonctionnalités principales du SDK et connexion XBOX

• PlayFabServices.dll : services PlayFab supplémentaires (recommandée)

YourGame/
├── YourGame.exe
├── libHttpClient.dll     // Required for HTTP operations
├── PlayFabCore.dll       // Required for authentication
├── PlayFabServices.dll   // Optional: For additional PlayFab services
├── PlayFabGameSave.dll   // Required for Game Saves
├── xgameruntime.dll      // Required for Xbox Live services
├── Steam_api64.dll
└── Other game files...

​

2. Prérequis de l’intégration Steam

​

Intégration de l’API Steam

// Initialize Steam API
bool steamAvailable = SteamAPI_Init();

​

Détection de la plateforme

bool DetectSteamDeck() {
    if (!SteamAPI_Init()) {
        return false;
    }
    
    return SteamUtils()->IsSteamRunningOnSteamDeck();
}

​

3. Implémentation des rappels d’interface utilisateur

​

Rappels d’interface utilisateur de Game Saves (requis pour les deux approches)

// Required Game Saves UI callbacks for Steam Deck (both approaches)
PFGameSaveUICallbacks callbacks{};
callbacks.progressCallback = OnPFGameSaveFilesUiProgress;                    // Sync progress
callbacks.syncFailedCallback = OnPFGameSaveFilesUiSyncFailed;               // Sync errors
callbacks.activeDeviceContentionCallback = OnPFGameSaveFilesUiActiveDeviceContention;  // Device conflicts
callbacks.conflictCallback = OnPFGameSaveFilesUiConflict;                   // Save conflicts
callbacks.outOfStorageCallback = OnPFGameSaveFilesUiOutOfStorage;           // Storage quota

HRESULT hr = PFGameSaveFilesSetUiCallbacks(&callbacks);
if (FAILED(hr)) {
    // Handle callback setup failure
}

// Optional: Additional active device changed callback
hr = PFGameSaveFilesSetActiveDeviceChangedCallback(&OnActiveDeviceChanged, nullptr);

• Boîtes de dialogue de progression : affichent la progression de la synchronisation pendant les opérations de sauvegarde
• Gestion des erreurs : affiche les messages d’échec de synchronisation et les options de nouvelle tentative
• Résolution des conflits : gère les conflits de sauvegarde entre appareils
• Contention entre appareils : gère les scénarios d’accès depuis plusieurs appareils
• Gestion de le stockage : informe les utilisateurs des problèmes de quota de stockage

​

Approche 1 : intégration à l’écosystème XBOX - implémentation complète

​

Vue d’ensemble

• Avoir terminé la configuration commune (sections 1 à 3 ci-dessus)
• Disposer d’un accès à un bac à sable de développement pour les tests
• Disposer de privilèges d’administrateur pour la configuration du Registre (développement/test uniquement)

​

1. Configuration du Registre

// Set sandbox before Xbox Live services initialization
// Only required when testing with non-retail sandboxes
if (isSteamDeck) {
    HRESULT hr = SteamIntegration::SetSandboxForSteamDeck("XDKS.1");
    if (FAILED(hr)) {
        // Handle sandbox setup failure - requires admin privileges
        return hr;
    }
}

• Clé : HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\XboxLive\Sandbox
• Valeur : ID du bac à sable de développement (par exemple, “XDKS.1”)
• Moment : doit être défini avant l’initialisation des services XBOX Live
• Privilèges : nécessite un accès administrateur
• Utilisation : requise uniquement pour les tests dans des bacs à sable autres que de production (environnements de développement/test)

​

2. Gestionnaires d’événements de plateforme XUser

​

A. Gestionnaires d’événements Remote Connect

// Handle remote authentication flow (QR code/URL)
XUserPlatformRemoteConnectEventHandlers remoteConnect{};
remoteConnect.context = nullptr;
remoteConnect.show = &OnRemoteConnectShow;     // Display QR code/URL dialog
remoteConnect.close = &OnRemoteConnectClose;   // Close authentication dialog
HRESULT hr = XUserPlatformRemoteConnectSetEventHandlers(nullptr, &remoteConnect);
if (FAILED(hr)) {
    // Handle event handler setup failure
}

​

B. Gestionnaires d’événements SPOP (invite de connexion)

// Handle SPOP sign-in prompt. See sample: ShowSpopPromptDialogForXUserOnSteamDeck
HRESULT hr = XUserPlatformSpopPromptSetEventHandlers(nullptr, &OnSpopPrompt, nullptr);
if (FAILED(hr)) {
    // Handle SPOP setup failure
}

​

3. Implémentation de l’interface utilisateur d’authentification

• Une boîte de dialogue Remote Connect : affiche le code QR et l’URL permettant aux utilisateurs de s’authentifier sur un autre appareil
• Une boîte de dialogue d’invite SPOP : permet aux utilisateurs de sélectionner/confirmer leur gamertag XBOX

​

4. Séquence d’initialisation

// 1. Check Steam availability and platform
bool steamAvailable = SteamIntegration::CheckSteamAvailability();
bool isSteamDeck = SteamIntegration::CheckIfSteamDeck();

// 2. Set Xbox Live sandbox (Steam Deck only, required for non-retail sandbox testing)
if (isSteamDeck) {
    HRESULT hr = SteamIntegration::SetSandboxForSteamDeck("XDKS.1");
    if (FAILED(hr)) {
        // Handle sandbox setup failure
        return hr;
    }
}

// 3. Initialize Xbox runtime
hr = XGameRuntimeInitialize();
if (FAILED(hr)) {
    return hr;
}

// 4. Initialize PlayFab Core and Services
hr = PFInitialize(nullptr);
if (FAILED(hr)) {
    return hr;
}
hr = PFServicesInitialize(nullptr); // Optional

// 5. Initialize XUser for Steam Deck
if (isSteamDeck) {
    hr = SteamIntegration::InitializeXUserForSteamDeck();
    if (FAILED(hr)) {
        return hr;
    }
}

// 6. Initialize Game Saves with appropriate callbacks
bool setUiCallbacks = isSteamDeck;
hr = InitializeGameSaves(setUiCallbacks);
if (FAILED(hr)) {
    return hr;
}

​

5. Implémentation de la déconnexion

void SignOutFromSteamDeck() {
    // Enumerate and delete Windows credentials with target names starting with "Xbl"
    DWORD count = 0;
    PCREDENTIALW* credentials = nullptr;
    
    if (CredEnumerateW(L"Xbl*", 0, &count, &credentials)) {
        for (DWORD i = 0; i < count; i++) {
            CredDeleteW(credentials[i]->TargetName, credentials[i]->Type, 0);
        }
        CredFree(credentials);
    }
    
    // Close Xbox user handles
    if (xboxUser) {
        XUserCloseHandle(xboxUser);
        xboxUser = nullptr;
    }
    
    // Close PlayFab user handles
    if (pfUser) {
        PFLocalUserCloseHandle(pfUser);
        pfUser = nullptr;
    }
    
    // Reset authentication state for clean re-authentication
    authenticationState = AuthState::NotAuthenticated;
}

​

6. Liste de contrôle des tests

• Flux d’authentification : testez l’authentification Remote Connect (code QR/URL)
• Rappels d’interface utilisateur : vérifiez que toutes les boîtes de dialogue de Game Saves s’affichent correctement
• Invites SPOP : testez la sélection et la confirmation du gamertag
• Persistance des informations d’identification : testez la persistance de la connexion d’un redémarrage de l’application à l’autre
• Déconnexion : vérifiez que les informations d’identification sont correctement effacées lors de la déconnexion
• Comportement de synchronisation : testez les synchronisations fréquentes et la synchronisation avant l’arrêt
• Prévention des pertes de données : vérifiez qu’une progression minimale est perdue en cas de fermeture forcée
• Synchronisation multiplateforme : testez la synchronisation des sauvegardes entre le Steam Deck, les consoles XBOX et le PC Microsoft Store
• Configuration du Registre : vérifiez que la configuration du bac à sable fonctionne dans les environnements de développement
• Gestionnaires d’événements XUser : confirmez le bon fonctionnement des gestionnaires Remote Connect et SPOP

​

Approche 2 : implémentation d’une identité personnalisée - implémentation complète

​

Vue d’ensemble

• Avoir terminé la configuration commune (sections 1 à 3 ci-dessus)
• Disposer d’un système d’identité de joueur personnalisé pour la production

• Aucune authentification XBOX requise
• Aucune configuration du Registre nécessaire
• Aucun privilège d’administrateur requis
• Interface utilisateur plus simple (pas de code QR ni de sélection de gamertag)

• Vous devez implémenter votre propre identité de joueur multiplateforme
• Aucune fonctionnalité sociale XBOX Live
• Nécessite des solutions personnalisées de passerelle entre plateformes

​

1. Authentification par identité personnalisée

// Custom identity authentication
if (isSteamDeck) {
    // Development/Testing: Use Steam user identity temporarily
    // Production: Implement your own cross-platform player identity system
    // Required for production since Steam Cloud handles Steam-only sync
    
    // Option 1: OpenID Connect Integration (Recommended)
    // If your identity system supports OpenID Connect, use LoginWithOpenIdConnect:
    // PFAuthenticationLoginWithOpenIdConnectRequest request = {};
    // request.connectionId = "YourOpenIdConnectConnectionId";
    // request.idToken = "YourOpenIdConnectToken";
    // PFAuthenticationLoginWithOpenIdConnectAsync(serviceConfigHandle, &request, ...);
    
    // Option 2: Custom Integration
    // Initialize your custom authentication system
    // Connect to your user accounts/login system
    // Integrate with PlayFab Game Saves using your player identity
    
    // Initialize Game Saves with your custom identity system
    // (Implementation details depend on your specific identity integration)
}

​

2. Séquence d’initialisation

// 1. Check Steam availability and platform
bool steamAvailable = SteamIntegration::CheckSteamAvailability();
bool isSteamDeck = SteamIntegration::CheckIfSteamDeck();

// 2. Initialize Xbox runtime (still required for Game Saves infrastructure)
HRESULT hr = XGameRuntimeInitialize();
if (FAILED(hr)) {
    return hr;
}

// 3. Initialize PlayFab Core and Services
hr = PFInitialize(nullptr);
if (FAILED(hr)) {
    return hr;
}
hr = PFServicesInitialize(nullptr); // Optional

// 4. Initialize your custom player identity system
hr = InitializeCustomPlayerIdentity();
if (FAILED(hr)) {
    return hr;
}

// 5. Initialize Game Saves with custom identity system
// Option A: OpenID Connect (if your identity system supports it)
// hr = PFAuthenticationLoginWithOpenIdConnectAsync(serviceConfigHandle, &openIdRequest, ...);
// Option B: Custom authentication integration
hr = InitializeGameSavesWithCustomIdentity();
if (FAILED(hr)) {
    return hr;
}

​

3. Implémentation de la déconnexion

void SignOutFromSteamDeck() {
    // Sign-out for custom identity implementation
    // No Xbox credential cleanup needed
    
    // Clean up your custom identity system
    SignOutFromCustomIdentitySystem();
    
    // Close PlayFab user handles
    if (pfUser) {
        PFLocalUserCloseHandle(pfUser);
        pfUser = nullptr;
    }
    
    // Clear local game state as needed
    ClearLocalGameState();
}

​

4. Liste de contrôle des tests

• Système d’identité personnalisé : testez votre système personnalisé d’authentification et d’identité des joueurs
• Authentification PlayFab : testez la connexion PlayFab à l’aide de LoginWithOpenIdConnect (si vous utilisez OpenID Connect) ou de votre méthode d’authentification personnalisée
• Synchronisation multiplateforme de Game Saves : testez la synchronisation des sauvegardes sur toutes les plateformes cibles
• Rappels d’interface utilisateur : vérifiez que toutes les boîtes de dialogue de Game Saves s’affichent correctement
• Résolution des conflits : testez les conflits de sauvegarde entre appareils de différentes plateformes
• Comportement de synchronisation : testez les synchronisations fréquentes et la synchronisation avant l’arrêt
• Prévention des pertes de données : vérifiez qu’une progression minimale est perdue en cas de fermeture forcée
• Authentification personnalisée : testez les flux de connexion/déconnexion de votre système d’identité
• Couverture des plateformes : testez sur toutes les plateformes ciblées par votre jeu (et pas uniquement les appareils Steam)
• Scénarios réseau : testez les transitions hors connexion/en ligne
• Performances : vérifiez que les opérations de synchronisation n’affectent pas les performances du jeu

​

Référence des exemples de code

• Emplacement : PlayFabGameSaveSample-Windows
• Fichiers clés :
  • SteamIntegration.cpp/.h : détection du Steam Deck, configuration du Registre, gestionnaires d’authentification
  • GameSaveIntegrationUI.cpp/.h : implémentations des rappels d’interface utilisateur pour les deux approches

​

Documentation connexe

• Guide d’implémentation avec le GDK d’octobre 2025
• Vue d’ensemble de Game Saves
• Démarrage rapide de Game Saves