> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Démarrage rapide macOS

> Ajoutez le SDK C PlayFab Services à un projet Xcode sur macOS et effectuez votre premier appel d'API PlayFab à l'aide de la bibliothèque client C native.

# Démarrage rapide : macOS

Prenez en main le SDK PlayFab Services pour macOS. Suivez ces étapes pour inclure les bibliothèques dans votre projet et essayer l'exemple de code des fonctionnalités PlayFab de base.

Ce démarrage rapide vous aide à effectuer votre premier appel d'API PlayFab à l'aide du SDK macOS. Avant de continuer, assurez-vous d'avoir suivi les étapes de [Démarrage rapide : Game Manager](/fr/services/playfab/live-service-management/gamemanager/quickstart), qui garantissent que vous disposez d'un compte PlayFab et que vous connaissez PlayFab Game Manager.

## Configuration requise

* Un [compte de développeur PlayFab](https://developer.playfab.com).
* L'IDE [XCode](https://developer.apple.com/xcode/) installé.

## Configuration du projet

Téléchargez le SDK PlayFab macOS dans votre projet depuis la [page des versions du SDK PlayFab](https://github.com/PlayFab/PlayFabCSdk/releases/latest).

### Intégrer le SDK C PlayFab à votre propre projet

#### Ajouter les binaires à votre jeu

Une fois vos binaires obtenus, par téléchargement ou par génération à partir du code source, vous devriez pouvoir les intégrer facilement à votre jeu/application. Vous devez ajouter les binaires suivants à votre jeu :

* HttpClient\_macOS.xcframework
* PlayFabCore\_macOS.xcframework
* PlayFabServices\_macOS.xcframework

Suivez ces instructions pour les ajouter :

1. Dans XCode, accédez à la cible souhaitée et sélectionnez-la.

2. Dans la section **General**, faites défiler vers le bas et, dans la section "**Frameworks, Libraries, and Embedded Content**", sélectionnez le signe "**+**".

3. Recherchez vos binaires **PlayFabServices** / **PlayFabCore** / **HttpClient** et sélectionnez les dossiers xcframework. (*Vous pouvez également sélectionner une bibliothèque spécifique en naviguant à l'intérieur des dossiers xcframework, mais il est recommandé d'importer le bundle xcframework, car il fonctionne à la fois pour les builds sur appareil et sur simulateur.*)

4. Une fois les binaires importés avec succès, HttpClient\_macOS, PlayFabCore\_macOS et PlayFabServices\_macOS apparaissent sous Frameworks, Libraries, and Embedded Content.

#### Ajouter les chemins de recherche des en-têtes

Une fois les binaires ajoutés, vous devez vous assurer que les chemins de recherche des en-têtes sont également correctement configurés.

1. Accédez à votre projet.

2. Sélectionnez "**Build Settings**", puis recherchez "**Header Search Paths**".

3. Mettez à jour la valeur de la propriété pour inclure les en-têtes du SDK. Ajoutez une référence aux en-têtes du dossier **include**. Exemple :
   ```
   PlayFabCSdk-macOS/include
   ```

## Initialisation et connexion

Suivez les étapes suivantes pour faire fonctionner quelques exemples d'appels PlayFab :

### En-têtes

Incluez **PFServices.h** pour accéder à toutes les fonctionnalités PlayFab incluses.

```cpp theme={null}
#include <playfab/services/PFServices.h>
```

### Initialisation

L'initialisation de PlayFab nécessite deux appels de fonction : **PFServicesInitialize** et **PFServiceConfigCreateHandle**. Le résultat de cette initialisation est un **PFServiceConfigHandle**. Vous fournissez ce handle à un appel de connexion ultérieur, afin de diriger l'appel vers le bon titre dans le back-end PlayFab.

```cpp theme={null}
    HRESULT hr = PFServicesInitialize(nullptr); // Add your own error handling when FAILED(hr) == true

    PFServiceConfigHandle serviceConfigHandle{ nullptr };

    hr = PFServiceConfigCreateHandle(
            "https://ABCDEF.playfabapi.com",    // PlayFab API endpoint - obtained in the Game Manager
            "ABCDEF",                           // PlayFab Title id - obtained in the Game Manager
            &serviceConfigHandle);
```

### Connexion

Une fois que vous disposez d'un **PFServiceConfigHandle**, vous pouvez l'utiliser pour effectuer un appel de connexion de joueur. Dans le SDK, utilisez une méthode **PFAuthenticationLoginWith\*Async** telle que **PFAuthenticationLoginWithAppleAsync**. Cette fonction vous permet de connecter un joueur à PlayFab à l'aide du **jeton d'identité d'un utilisateur Apple**. (*consultez la documentation d'Apple sur [l'authentification des utilisateurs avec Sign in with Apple](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_rest_api/authenticating_users_with_sign_in_with_apple)*).

Après un appel de connexion, vous pouvez vérifier l'état de l'appel avec **XAsyncGetStatus**. L'état est initialement **E\_PENDING** et passe à **S\_OK** une fois l'appel terminé avec succès. Si l'appel échoue pour une raison quelconque, l'état reflète cet échec. La gestion des erreurs fonctionne de cette manière pour tous les appels PlayFab Services.

Avec un résultat **S\_OK**, vous obtenez un **PFEntityHandle**. Vous utilisez ce handle pour effectuer les appels PlayFab suivants en tant que joueur connecté. Il contient tous les éléments nécessaires pour s'authentifier auprès du service PlayFab en tant que ce joueur.

```cpp theme={null}
PFAuthenticationLoginWithAppleRequest request{};
request.createAccount = true;
request.identityToken = identityToken; // A user identity token obtained from Apple

XAsyncBlock async{};
hr = PFAuthenticationLoginWithAppleAsync(serviceConfigHandle, &request, &async); // Add your own error handling when FAILED(hr) == true
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

std::vector<char> loginResultBuffer;
PFAuthenticationLoginResult const* loginResult;
size_t bufferSize;
hr = PFAuthenticationLoginWithAppleGetResultSize(&async, &bufferSize);
loginResultBuffer.resize(bufferSize);

PFEntityHandle entityHandle{ nullptr };
hr = PFAuthenticationLoginWithAppleGetResult(&async, &entityHandle, loginResultBuffer.size(), loginResultBuffer.data(), &loginResult, nullptr);
```

## Appels de service

Une fois le joueur connecté, vous pouvez effectuer des appels au back-end PlayFab. Voici un exemple d'appel permettant d'obtenir les fichiers stockés dans PlayFab pour le joueur actuel.

### Obtenir l'EntityKey

Pour certains appels à PlayFab, il peut être utile de connaître la **PFEntityKey** du joueur. Une fois que vous disposez d'un **PFEntityToken**, vous pouvez récupérer une **PFEntityKey** avec **PFEntityGetEntityKey**.

```cpp theme={null}
    PFEntityKey const* pEntityKey{};
    std::vector<char> entityKeyBuffer;
    size_t size{};
    HRESULT hr = PFEntityGetEntityKeySize(entityHandle, &size); // Add your own error handling when FAILED(hr) == true

    entityKeyBuffer.resize(size);
    hr = PFEntityGetEntityKey(entityHandle, entityKeyBuffer.size(), entityKeyBuffer.data(), &pEntityKey, nullptr);
```

### Appeler GetFiles

Tous les appels PlayFab suivent un modèle similaire : préparation de l'objet de requête, appel (à l'aide du **PFEntityHandle** obtenu lors de la connexion), création d'un objet destiné à recevoir la réponse, puis appel d'une fonction **GetResult** pour remplir le conteneur nouvellement créé.

```cpp theme={null}
    XAsyncBlock async{};
    PFDataGetFilesRequest requestFiles{};
    requestFiles.entity = pEntityKey;

    HRESULT hr = PFDataGetFilesAsync(entityHandle, &requestFiles, &async); // Add your own error handling when FAILED(hr) == true
    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

    size_t resultSize;
    hr = PFDataGetFilesGetResultSize(&async, &resultSize);

    std::vector<char> getFilesResultBuffer(resultSize);
    PFDataGetFilesResponse* getFilesResponseResult{ nullptr };
    hr = PFDataGetFilesGetResult(&async, getFilesResultBuffer.size(), getFilesResultBuffer.data(), &getFilesResponseResult, nullptr);
```

## Nettoyage

Lorsque votre jeu est prêt à s'arrêter, ou si vous devez nettoyer PlayFab pour une autre raison, veillez à fermer tous les handles ouverts et à appeler **PFServicesUninitializeAsync**.

```cpp theme={null}
    PFEntityCloseHandle(entityHandle);
    entityHandle = nullptr;

    PFServiceConfigCloseHandle(serviceConfigHandle);
    serviceConfigHandle = nullptr;

    XAsyncBlock async{};
    HRESULT hr = PFServicesUninitializeAsync(&async); // Add your own error handling when FAILED(hr) == true
    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
```

## Modèle d'API asynchrone

Le SDK PlayFab Services suit le [modèle de programmation asynchrone](https://learn.microsoft.com/en-us/gaming/gdk/_content/gc/system/overviews/async-programming-model) implémenté dans le GDK. Ce modèle de programmation implique l'utilisation de tâches et de files d'attente de tâches fournies par la [bibliothèque XAsync](/fr/build/core-features/common/async/async-libraries/async-library-xasync). Ce modèle est cohérent avec les autres fonctions et extensions du GDK (comme l'API XBOX Services). Bien qu'il introduise une certaine complexité, il offre également un haut niveau de contrôle sur les opérations asynchrones.

Cet exemple montre comment effectuer un appel asynchrone à **PFDataGetFilesAsync**.

```cpp theme={null}
    auto async = std::make_unique<XAsyncBlock>();
    async->callback = [](XAsyncBlock* async)
    {
        std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // take ownership of XAsyncBlock

        size_t resultSize;
        HRESULT hr = PFDataGetFilesGetResultSize(async, &resultSize);
        if (SUCCEEDED(hr))
        {
            std::vector<char> getFilesResultBuffer(resultSize);
            PFDataGetFilesResponse* getFilesResponseResult{ nullptr };
            PFDataGetFilesGetResult(async, getFilesResultBuffer.size(), getFilesResultBuffer.data(), &getFilesResponseResult, nullptr);
        }
    };

    PFDataGetFilesRequest requestFiles{};
    requestFiles.entity = m_pEntityKey;
    HRESULT hr = PFDataGetFilesAsync(m_entityHandle, &requestFiles, async.get());
    if (SUCCEEDED(hr))
    {
        async.release(); // at this point, the callback will be called so release the unique ptr
    }

```

## Gestion des erreurs

Les opérations **XAsync** terminées renvoient des codes d'état HTTP. Un code d'état d'erreur se traduit par un **HRESULT** d'échec, tel que **HTTP\_E\_STATUS\_NOT\_FOUND**, lors de l'appel de **XAsyncGetStatus()** ou de l'une des API **PF\*Get()**.

Pour afficher les messages d'erreur détaillés renvoyés par le service, consultez la section suivante sur le débogage. Ces messages d'erreur détaillés peuvent être utiles pendant le développement pour mieux comprendre comment le service PlayFab réagit aux requêtes du client.

## Débogage

Le moyen le plus simple d'afficher les résultats et de déboguer les appels du SDK PlayFab Services consiste à activer le [traçage de débogage](/fr/services/playfab/sdks/c/tracing). L'activation du traçage de débogage vous permet à la fois d'afficher les résultats dans la fenêtre de sortie du débogueur et de les intégrer aux journaux de votre jeu.

## Voir aussi

[Documentation de référence de l'API](/fr/services/playfab/api-references/c/pfauthentication/pfauthentication_members)


## Related topics

- [Plateformes prises en charge par PlayFab](/fr/services/playfab/sdks/platforms/index.md)
- [Langages pris en charge par PlayFab](/fr/services/playfab/sdks/languages/index.md)
- [Démarrage rapide de Party](/fr/services/playfab/multiplayer/networking/quickstart.md)
- [PlayFab Services pour macOS](/fr/services/playfab/sdks/platforms/macos.md)
- [Démarrage rapide NodeJS](/fr/services/playfab/sdks/nodejs/quickstart.md)