Guide de démarrage rapide : intégration de PlayFab Online Subsystem avec le plugiciel PlayFab de la marketplace Unreal Engine

Ce guide de démarrage rapide vous aide à intégrer le plugiciel PlayFab SDK de la marketplace Unreal Engine (UE) dans votre projet existant intégrant PlayFab Online Subsystem (OSS). Le plugiciel PlayFab SDK permet d’effectuer des opérations PlayFab d’administration, client et serveur, comme l’authentification des joueurs, la gestion des objets virtuels et des devises, et la création de fonctionnalités sociales. Utilisé conjointement avec PlayFab Online Subsystem, il permet à votre projet d’accéder à l’ensemble des fonctionnalités PlayFab pour les projets Unreal Engine. Lorsque vous utilisez PlayFab OSS ou le plugiciel PlayFab SDK indépendamment l’un de l’autre, la première étape consiste à authentifier un utilisateur. Si vous utilisez les deux dans le même projet sans la configuration appropriée, PlayFab OSS et le plugiciel PlayFab SDK effectueront chacun un appel d’authentification distinct pour le même utilisateur. Ce guide de démarrage rapide vous aide à vous authentifier au moyen de PlayFab OSS et à réutiliser cette authentification avec le plugiciel PlayFab SDK, pour une expérience d’authentification utilisateur fluide.

Prérequis

Assurez-vous d’intégrer PlayFab OSS en tant que plugiciel dans votre fichier <game>.build.cs. Dans l’exemple ci-dessous, nous créons une option de bascule pour permettre l’intégration et définissons une définition pour permettre une protection #ifdef.

// PlayFab OnlineSubsystem Plugin Settings.
//
// While the PlayFab OSS is integrated with the game at an engine level, we cannot directly access
// PF OSS headers unless we integrate it as a plugin.
//
// `bOSSPlayFabAsPlugin` must be set to true to expose the PlayFab OSS headers directly to the game.
bool bOSSPlayFabAsPlugin = false;
if (bOSSPlayFabAsPlugin)
{
    PublicDependencyModuleNames.AddRange(new string[] { "OnlineSubsystemPlayFab" });
    PublicDefinitions.Add("WITH_OSS_PLAYFAB=1");
}

Assurez-vous d’intégrer le plugiciel PlayFab SDK dans votre fichier <game>.build.cs. Dans l’exemple ci-dessous, nous créons une option de bascule pour permettre l’intégration et définissons une définition pour permettre une protection #ifdef.

// PlayFab SDK Plugin Settings.
//
// `bPlayFabPlugin` must be set to true to enable compilation and integration with the PlayFab
// SDK Plugin.
// Ensure that the PF SDK Plugin is installed via Engine plugin or as a local game plugin.
bool bPlayFabPlugin = false;
if (bPlayFabPlugin)
{
    PrivateDependencyModuleNames.AddRange(new string[] { "PlayFab", "PlayFabCpp", "PlayFabCommon" });
    PublicDefinitions.Add("WITH_PLAYFAB_PLUGIN=1");
}

Après avoir mis à jour votre fichier <game.build.cs> (et à chaque mise à jour ultérieure), assurez-vous de régénérer les fichiers de projet Visual Studio de votre jeu en cliquant avec le bouton droit sur votre fichier .uproject et en sélectionnant Generate Visual Studio Project Files.

PlayFab OSS propose maintenant un délégué public AuthenticateUserComplete qui se déclenche à la fin du flux d’authentification utilisateur de PlayFab OSS. Liez-vous à ce délégué pour récupérer les détails de votre authentification PlayFab OSS.

/**
* Delegate used on the completion of FOnlineIdentityPlayFab::AuthenticateUser().
*
* @param LocalUserNum the controller number of the associated user that made the request
* @param bWasSuccessful true if authentication was successful, false if there was an error
* @param PlatformUserIdStr user identifier returned from the service.
* @param ErrorStr string representing the error condition
*/
DECLARE_MULTICAST_DELEGATE_FourParams(FOnAuthenticateUserComplete, int32 /*LocalUserNum*/, bool /*bWasSuccessful*/, const FString& /*PlatformUserIdStr*/, const FString& /*ErrorStr*/);
typedef FOnAuthenticateUserComplete::FDelegate FOnAuthenticateUserCompleteDelegate;

Étapes

Vous pouvez également passer directement à l’exemple de code complet.

Inclure les en-têtes appropriés

#ifdef WITH_OSS_PLAYFAB
#include "OnlineSubsystemPlayFab.h"
#endif // WITH_OSS_PLAYFAB

#ifdef WITH_PLAYFAB_PLUGIN
#include "PlayFab.h"
#include "PlayFabCommon.h"
#include "Core/PlayFabClientDataModels.h"
#endif // WITH_PLAYFAB_PLUGIN

Récupérer PlayFab OSS

FOnlineSubsystemPlayFab* PFOnlineSub = static_cast<FOnlineSubsystemPlayFab*>(IOnlineSubsystem::Get(TEXT("PLAYFAB")));

Se lier au délégué AuthenticateUserComplete

const FOnlineIdentityPlayFabPtr PlayFabIdentityInterface = PFOnlineSub->GetIdentityInterfacePlayFab();
PlayFabIdentityInterface->AddOnAuthenticateUserCompleteDelegate_Handle
(
    0, // LocalUserNum
    FOnAuthenticateUserCompleteDelegate::CreateUObject(this, &UGameInstance::OnAuthenticateUserComplete)
);

Les fonctions liées à ce délégué doivent avoir la même signature que le délégué. Par exemple :

void UGameInstance::OnAuthenticateUserComplete(int32 localUserNum, bool bWasSuccessful, const FString& platformUserIdStr, const FString& error)

Vous pouvez également lier une expression lambda au délégué. Par exemple :

// We don't pass the `FOnlineIdentityPlayFabPtr` pointer through the lambda capture since the original
// local isn't guaranteed to live longer than the lambda and we want to avoid dangling references.
//
// You can retrieve `FOnlineIdentityPlayFabPtr` again inside the lambda.
PlayFabIdentityInterface->AddOnAuthenticateUserCompleteDelegate_Handle
(
    0, // LocalUserNum
    FOnAuthenticateUserCompleteDelegate::CreateLambda([this](int32 localUserNum, bool bWasSuccessful, const FString& platformUserIdStr, const FString& error)
    {
        // lambda execution
    });
)

Gérer le résultat de l’authentification : dans la fonction liée au délégué, gérez le résultat de l’authentification. Si l’authentification réussit, récupérez l’utilisateur local authentifié au moyen du platformUserIdStr provenant du déclenchement du délégué. Construisez ensuite un LoginResult PlayFab à partir du LocalUser de PlayFab OSS.

void UGameInstance::OnAuthenticateUserComplete(int32 localUserNum, bool bWasSuccessful, const FString& platformUserIdStr, const FString& error)
{
    if (!bWasSuccessful)
    {
        UE_LOG(LogOnlineGame, Error, TEXT("OSS PlayFab AuthenticateLocalUser Failed. Error: %s"), *error);
        return;
    }

    UE_LOG(LogOnlineGame, Display, TEXT("[%s] AuthenticateLocalUser Complete"), ANSI_TO_TCHAR(__FUNCTION__));

    FOnlineSubsystemPlayFab* PFOnlineSub = static_cast<FOnlineSubsystemPlayFab*>(IOnlineSubsystem::Get(TEXT("PLAYFAB")));
    const FOnlineIdentityPlayFabPtr PlayFabIdentityInterface = PFOnlineSub->GetIdentityInterfacePlayFab();

    if (PlayFabIdentityInterface)
    {
        if (const auto LocalUser = PlayFabIdentityInterface->GetPartyLocalUserFromPlatformIdString(platformUserIdStr))
        {
            // Setting PlayFab SDK Settings for future API calls
            auto& PFCommonModule = IPlayFabCommonModuleInterface::Get();
            PFCommonModule.SetClientSessionTicket(LocalUser->GetSessionTicket());
            PFCommonModule.SetEntityToken(LocalUser->GetEntityToken());

            // Create EntityKey
            auto LocalEntityKey = MakeShared<PlayFab::ClientModels::FEntityKey>();
            LocalEntityKey->Id = LocalUser->GetEntityId();
            LocalEntityKey->Type = LocalUser->GetEntityType();

            // Create EntityToken
            auto LocalEntityToken = MakeShared<PlayFab::ClientModels::FEntityTokenResponse>();
            LocalEntityToken->Entity = LocalEntityKey;
            LocalEntityToken->EntityToken = LocalUser->GetEntityToken();

            // Create LoginResult
            PlayFab::ClientModels::FLoginResult LoginResult;
            LoginResult.EntityToken = LocalEntityToken;
            LoginResult.LastLoginTime = LocalUser->GetEntityTokenUpdateTime();
            LoginResult.PlayFabId = LocalUser->GetPlayFabId();
            LoginResult.SessionTicket = LocalUser->GetSessionTicket();

            // With `LoginResult` populated, we can now use the PlayFab SDK Plugin APIs
            // however we wish. This state is considered "authenticated".
            //
            // This delegate signature functions does not return anything. You can pass `LoginResult`
            // out of this function however you wish.
            // 
            // Example psuedocode for a non-existent function that takes `LoginResult` as a parameter:
            // void UGameInstance::OnAPILoginSuccess(PlayFab::ClientModels::FLoginResult LoginResult);
        }
    }
}

Utiliser les API du plugiciel PlayFab SDK : une fois LoginResult renseigné, vous pouvez utiliser les API du plugiciel PlayFab SDK comme vous le souhaitez. Cet état est considéré comme « authentifié ».

Exemple de code complet

#ifdef WITH_OSS_PLAYFAB
#include "OnlineSubsystemPlayFab.h"
#endif // WITH_OSS_PLAYFAB

#ifdef WITH_PLAYFAB_PLUGIN
#include "PlayFab.h"
#include "PlayFabCommon.h"
#include "Core/PlayFabClientDataModels.h"
#endif // WITH_PLAYFAB_PLUGIN

...

void UGameInstance::Init()
{
    Super::Init();
    ...

    // This is an example scenario of integrating the PlayFab OnlineSubsystem with the
    // PlayFab SDK Plugin.
    //
    // In this scenario, you can authenticate via the PlayFab OSS,
    // and then re-use that authentication with the PlayFab SDK Plugin.
    // 
    // PF OSS offers a public `AuthenticateUserComplete` delegate that can be bound;
    // this delegate triggers on completion of the PF OSS user authentication flow.
    // 
    // Below is an example of a game binding to that delegate, retrieving the
    // authenticated local user via the `platformUserIdStr` from the delegate
    // trigger, and then constructing a PlayFab `LoginResult` from the PF OSS
    // `LocalUser.`
    // 
    // These definitions are defined in `<game>.build.cs`.
#if defined(WITH_OSS_PLAYFAB) && defined(WITH_PLAYFAB_PLUGIN)
    // Explicitly retrieve the PlayFab OSS - we can't assume it's the default OSS.
    FOnlineSubsystemPlayFab* PFOnlineSub = static_cast<FOnlineSubsystemPlayFab*>(IOnlineSubsystem::Get(TEXT("PLAYFAB")));

    UE_LOG(LogOnlineGame, Warning, TEXT("Retrieved PFOnlineSub"));

    if (PFOnlineSub)
    {
        const FOnlineIdentityPlayFabPtr PlayFabIdentityInterface = PFOnlineSub->GetIdentityInterfacePlayFab();

        PlayFabIdentityInterface->AddOnAuthenticateUserCompleteDelegate_Handle
        (
            0, // LocalUserNum
            FOnAuthenticateUserCompleteDelegate::CreateUObject(this, &UGameInstance::OnAuthenticateUserComplete)
        );
    }
    else
    {
        UE_LOG(LogOnlineGame, Error, TEXT("UGameInstance::Init: Unable to find OnlineSubsystemPlayFab"));
    }
#endif // WITH_OSS_PLAYFAB && WITH_PLAYFAB_PLUGIN

    ...
}

void UGameInstance::OnAuthenticateUserComplete(int32 localUserNum, bool bWasSuccessful, const FString& platformUserIdStr, const FString& error)
{
    if (!bWasSuccessful)
    {
        UE_LOG(LogOnlineGame, Error, TEXT("OSS PlayFab AuthenticateLocalUser Failed. Error: %s"), *error);
        return;
    }

    UE_LOG(LogOnlineGame, Display, TEXT("[%s] AuthenticateLocalUser Complete"), ANSI_TO_TCHAR(__FUNCTION__));

    FOnlineSubsystemPlayFab* PFOnlineSub = static_cast<FOnlineSubsystemPlayFab*>(IOnlineSubsystem::Get(TEXT("PLAYFAB")));
    const FOnlineIdentityPlayFabPtr PlayFabIdentityInterface = PFOnlineSub->GetIdentityInterfacePlayFab();

    if (PlayFabIdentityInterface)
    {
        if (const auto LocalUser = PlayFabIdentityInterface->GetPartyLocalUserFromPlatformIdString(platformUserIdStr))
        {
            // Setting PlayFab SDK Settings for future API calls
            auto& PFCommonModule = IPlayFabCommonModuleInterface::Get();
            PFCommonModule.SetClientSessionTicket(LocalUser->GetSessionTicket());
            PFCommonModule.SetEntityToken(LocalUser->GetEntityToken());

            // Create EntityKey
            auto LocalEntityKey = MakeShared<PlayFab::ClientModels::FEntityKey>();
            LocalEntityKey->Id = LocalUser->GetEntityId();
            LocalEntityKey->Type = LocalUser->GetEntityType();

            // Create EntityToken
            auto LocalEntityToken = MakeShared<PlayFab::ClientModels::FEntityTokenResponse>();
            LocalEntityToken->Entity = LocalEntityKey;
            LocalEntityToken->EntityToken = LocalUser->GetEntityToken();

            // Create LoginResult
            PlayFab::ClientModels::FLoginResult LoginResult;
            LoginResult.EntityToken = LocalEntityToken;
            LoginResult.LastLoginTime = LocalUser->GetEntityTokenUpdateTime();
            LoginResult.PlayFabId = LocalUser->GetPlayFabId();
            LoginResult.SessionTicket = LocalUser->GetSessionTicket();

            // With `LoginResult` populated, we can now use the PlayFab SDK Plugin APIs
            // however we wish. This state is considered "authenticated".
            //
            // This delegate signature functions does not return anything. You can pass `LoginResult`
            // out of this function however you wish.
            // 
            // Example psuedocode for a non-existent function that takes `LoginResult` as a parameter:
            // void UGameInstance::OnAPILoginSuccess(PlayFab::ClientModels::FLoginResult LoginResult);
        }
    }
}

XBOX Services

PlayFab

Intégrer le plugiciel PlayFab de la marketplace Unreal Engine

Guide de démarrage rapide : intégration de PlayFab Online Subsystem avec le plugiciel PlayFab de la marketplace Unreal Engine

Prérequis

Étapes

Exemple de code complet

​Guide de démarrage rapide : intégration de PlayFab Online Subsystem avec le plugiciel PlayFab de la marketplace Unreal Engine

​Prérequis

​Étapes

​Exemple de code complet

Guide de démarrage rapide : intégration de PlayFab Online Subsystem avec le plugiciel PlayFab de la marketplace Unreal Engine

Prérequis

Étapes

Exemple de code complet