> ## 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.

# クイックスタート macOS

> macOS 上の Xcode プロジェクトに PlayFab Services C SDK を追加し、ネイティブ C クライアントライブラリを使用して最初の PlayFab API 呼び出しを行います。

# クイックスタート: macOS

macOS 向けの PlayFab Services SDK を始めましょう。次の手順に従って、ライブラリをプロジェクトに含め、基本的な PlayFab 機能のサンプルコードを試してください。

このクイックスタートは、macOS SDK を使用して最初の PlayFab API 呼び出しを行うのに役立ちます。続行する前に、[クイックスタート: Game Manager](/services/playfab/live-service-management/gamemanager/quickstart) の手順を完了し、PlayFab アカウントを持っており、PlayFab Game Manager に慣れていることを確認してください。

## 要件

* [PlayFab 開発者アカウント](https://developer.playfab.com)。
* [XCode](https://developer.apple.com/xcode/) IDE がインストールされていること。

## プロジェクトのセットアップ

[PlayFab SDK リリースページ](https://github.com/PlayFab/PlayFabCSdk/releases/latest)から PlayFab macOS SDK をプロジェクトにダウンロードします。

### PlayFab C SDK を独自のプロジェクトに統合する

#### バイナリをゲームに追加する

ダウンロードまたはソースからビルドしてバイナリを入手した後、ゲーム/アプリに簡単に統合できます。以下のバイナリをゲームに追加する必要があります:

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

これらを追加するには、以下の手順に従います:

1. XCode で目的のターゲットに移動し、それを選択します。

2. **General** セクションで下にスクロールし、"**Frameworks, Libraries, and Embedded Content**" セクションで "**+**" 記号を選択します。

3. **PlayFabServices** / **PlayFabCore** / **HttpClient** バイナリを検索し、xcframework フォルダーを選択します。(*xcframework フォルダー内に移動して特定のライブラリを選択することもできますが、xcframework バンドルをインポートすることをおすすめします。デバイスとシミュレーターのビルドの両方で機能するためです。*)

4. バイナリを正常にインポートすると、HttpClient\_macOS、PlayFabCore\_macOS、および PlayFabServices\_macOS が Frameworks, Libraries, and Embedded Content の下にリスト表示されます。

#### ヘッダー検索パスの追加

バイナリを追加したら、ヘッダー検索パスも正しく設定されていることを確認する必要があります。

1. プロジェクトに移動します。

2. "**Build Settings**" を選択し、"**Header Search Paths**" を検索します。

3. SDK ヘッダーを含めるようにプロパティ値を更新します。**include** フォルダーにあるヘッダーへの参照を追加します。例:
   ```
   PlayFabCSdk-macOS/include
   ```

## 初期化とサインイン

次の手順に従って、いくつかの PlayFab サンプル呼び出しを動作させます:

### ヘッダー

含まれるすべての PlayFab 機能にアクセスするために **PFServices.h** をインクルードします。

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

### 初期化

PlayFab の初期化には、**PFServicesInitialize** と **PFServiceConfigCreateHandle** の 2 つの関数呼び出しが必要です。この初期化の結果は **PFServiceConfigHandle** です。このハンドルを後続のログイン呼び出しに提供して、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);
```

### サインイン

**PFServiceConfigHandle** を取得したら、それを使用してプレイヤーのログイン呼び出しを行うことができます。SDK では、**PFAuthenticationLoginWithAppleAsync** のような **PFAuthenticationLoginWith\*Async** メソッドを使用します。この関数を使用すると、**Apple ユーザーの identity token** を使用してプレイヤーを PlayFab にログインさせることができます。(*[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)に関する Apple のドキュメントを参照してください*)。

ログイン呼び出しを行った後、**XAsyncGetStatus** で呼び出しのステータスを確認できます。ステータスは **E\_PENDING** から始まり、呼び出しが正常に完了すると **S\_OK** に変わります。何らかの理由で呼び出しが失敗した場合、ステータスはその失敗を反映します。すべての PlayFab Services 呼び出しのエラー処理はこのように機能します。

**S\_OK** の結果とともに、**PFEntityHandle** が返されます。このハンドルを使用して、ログインしたプレイヤーとして後続の PlayFab 呼び出しを行います。これには、そのプレイヤーとして PlayFab サービスで認証するために必要なあらゆるマテリアルが含まれています。

```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);
```

## サービス呼び出し

プレイヤーをログインさせた後、PlayFab バックエンドへの呼び出しを行えます。現在のプレイヤーの PlayFab に保存されたファイルを取得する呼び出しの例を次に示します。

### EntityKey の取得

PlayFab への一部の呼び出しに役立つのは、プレイヤーの **PFEntityKey** を知ることです。**PFEntityToken** を取得したら、**PFEntityGetEntityKey** で **PFEntityKey** を取得できます。

```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);
```

### GetFiles の呼び出し

すべての PlayFab 呼び出しは、リクエストオブジェクトを準備し、呼び出しを行い (ログインからの **PFEntityHandle** を使用)、レスポンスを受け取るオブジェクトを作成し、次に **GetResult** 関数を呼び出して新しく作成されたコンテナーを埋めるという同様のパターンに従います。

```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);
```

## クリーンアップ

ゲームをシャットダウンする準備ができたときや、その他の理由で PlayFab をクリーンアップする必要があるときは、開いているすべてのハンドルを閉じ、**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
```

## 非同期 API パターン

PlayFab Services SDK は、GDK で実装された[非同期プログラミングモデル](https://learn.microsoft.com/en-us/gaming/gdk/_content/gc/system/overviews/async-programming-model)に従います。このプログラミングモデルには、[XAsync ライブラリ](/build/core-features/common/async/async-libraries/async-library-xasync)によって提供されるタスクとタスクキューの使用が含まれます。このモデルは、他の GDK 関数や拡張機能 (XBOX Services API など) と一貫しています。若干の複雑さは導入しますが、非同期操作に対する高度な制御ももたらします。

この例は、**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
    }

```

## エラー処理

完了した **XAsync** 操作は HTTP ステータスコードを返します。エラーステータスコードは、**XAsyncGetStatus()** または **PF\*Get()** API のいずれかを呼び出すときに、**HTTP\_E\_STATUS\_NOT\_FOUND** のような失敗の **HRESULT** として現れます。

サービスから返される詳細なエラーメッセージを確認するには、デバッグに関する次のセクションを参照してください。これらの詳細なエラーメッセージは、開発中に、PlayFab サービスがクライアントからのリクエストにどのように反応するかをよりよく理解するのに役立ちます。

## デバッグ

PlayFab Services SDK の結果を確認し、任意の呼び出しをデバッグする最も簡単な方法は、[デバッグトレース](/services/playfab/sdks/c/tracing)を有効にすることです。デバッグトレースを有効にすると、デバッガー出力ウィンドウで結果を確認し、結果をゲーム独自のログにフックすることができます。

## 関連項目

[API リファレンスドキュメント](/services/playfab/api-references/c/pfauthentication/pfauthentication_members)


## Related topics

- [PlayFab がサポートする言語](/ja-jp/services/playfab/sdks/languages/index.md)
- [PlayFab がサポートするプラットフォーム](/ja-jp/services/playfab/sdks/platforms/index.md)
- [PlayFab Services SDK](/ja-jp/services/playfab/sdks/c/index.md)
- [NodeJS クイックスタート](/ja-jp/services/playfab/sdks/nodejs/quickstart.md)
- [Corona 向け Lua クイックスタート](/ja-jp/services/playfab/sdks/lua/quickstart-corona.md)