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

# 適用於原生與 Phaser 的 JavaScript 快速入門

> 安裝 PlayFab JavaScript 用戶端程式庫，並在瀏覽器或 Phaser 遊戲中進行您的第一次 PlayFab API 呼叫以驗證玩家。

# 快速入門：適用於 JavaScript 的 PlayFab 用戶端程式庫

開始使用適用於 JavaScript 的 PlayFab 用戶端程式庫來驗證玩家。請依照步驟安裝套件，並試用基本工作的範例程式碼。

## 必要條件

* [PlayFab 開發人員帳戶](https://developer.playfab.com)。如需建立遊戲和尋找 TitleId 的相關資訊，請參閱 [Game Manager 快速入門](/zh-TW/services/playfab/live-service-management/gamemanager/quickstart)。

本快速入門指南適用於任何能夠執行網頁瀏覽器的作業系統。

## JavaScript 專案設定

您必須先擁有 [PlayFab 開發人員帳戶](https://developer.playfab.com)，才能呼叫任何 PlayFab API。如需建立遊戲和尋找 TitleId 的相關資訊，請參閱 [Game Manager 快速入門](/zh-TW/services/playfab/live-service-management/gamemanager/quickstart)。

作業系統：本指南適用於任何能夠執行網頁瀏覽器的作業系統。

若要設定新專案，請建立一個新資料夾，其中包含兩個空白文字檔：

* `PlayFabGettingStarted.html`
* `PlayFabGettingStarted.js`

就這樣，PlayFab 安裝完成！

## 程式碼範例

本指南提供進行第一次 PlayFab API 呼叫所需的最少步驟。您可以在網頁上看到確認訊息。如需參數和傳回值的詳細資訊，建議您先使用 [Postman 範本](/zh-TW/services/playfab/sdks/postman/postman-quickstart)。

### 驗證用戶端

在您慣用的文字編輯器中，依下列方式更新 `PlayFabGettingStarted.html` 的內容：

```html theme={null}
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>PlayFab JavaScript Unit Tests</title>
    <script type="text/javascript" src="https://download.playfab.com/PlayFabClientApi.js"></script>
    <script type="text/javascript" src="PlayFabGettingStarted.js"></script>
</head>
<body>
    PlayFab Getting Started Guide<br />
    TitleID: <input type="text" id="titleId" value="144"><br />
    CustomID: <input type="text" id="customId" value="GettingStartedGuide"><br />
    <input type="button" value="Call LoginWithCustomID" onclick="DoExampleLoginWithCustomID()"><br />
    Result:<br />
    <textarea id="resultOutput" cols="60" rows="5"></textarea><br />
</body>
</html>
```

在您慣用的文字編輯器中，依下列方式更新 `PlayFabGettingStarted.js` 的內容：

```javascript theme={null}
function DoExampleLoginWithCustomID(){
    PlayFab.settings.titleId = document.getElementById("titleId").value;
    var loginRequest = {
        // Currently, you need to look up the required and optional keys for this object in the API reference for LoginWithCustomID. See the Request Headers and Request Body.
        TitleId: PlayFab.settings.titleId,
        CustomId: document.getElementById("customId").value,
        CreateAccount: true
    };

    PlayFabClientSDK.LoginWithCustomID(loginRequest, LoginCallback);
}

// callback functions take two parameters: result and error
// see callback functions in JavaScript if unclear
var LoginCallback = function (result, error) {
    if (result !== null) {
        document.getElementById("resultOutput").innerHTML = "Congratulations, you made your first successful API call!";
    } else if (error !== null) {
        document.getElementById("resultOutput").innerHTML =
            "Something went wrong with your first API call.\n" +
            "Here's some debug information:\n" +
            PlayFab.GenerateErrorReport(error);
    }
}
```

若要查閱此範例中 loginRequest 物件的正確格式，請參閱 [LoginWithCustomID](xref:titleid.playfabapi.com.client.authentication.loginwithcustomid) 的 API 參考。

## 執行程式碼

1. 在您慣用的瀏覽器中開啟 `PlayFabGettingStarted.html`。
2. 選取 **Call LoginWithCustomID** 按鈕。
3. 您應該會在 Result 區段中看到下列文字：
   "Congratulations, you made your first successful API call!"

現在，您可以開始進行其他 API 呼叫並建置您的遊戲。

如需所有可用用戶端 API 呼叫的清單，請參閱 [PlayFab API 參考](/zh-TW/services/playfab/api-references)文件。

## 解構程式碼

本節會詳細說明程式碼的每個部分。

HTML 檔案中有幾行重要的程式碼：

```html theme={null}
<script type="text/javascript" src="https://download.playfab.com/PlayFabClientApi.js"></script>
```

這一行會直接從 PlayFab CDN 載入 Client-SDK。我們的 CDN 一律裝載最新版本的 PlayFabSDK。下載檔案並使用固定版本對您而言可能會更安全：[PlayFab JavaScript SDK](https://aka.ms/playfabjavascriptsdkdownload)

```html theme={null}
<script type="text/javascript" src="PlayFabGettingStarted.js"></script>
...
<input type="button" value="Call LoginWithCustomID" onclick="DoExampleLoginWithCustomID()"><br />
```

如上所示，`PlayFabGettingStarted.js` 包含 `DoExampleLoginWithCustomID` 函式。這幾行會將我們的 js 檔案繫結至網頁，並叫用該指令碼中的 `DoExampleLoginWithCustomID` 函式。其他部分都只是 GUI。

`PlayFabClientSDK` 中的函式是以對應的 HTTP 要求命名的。例如，`LoginWithCustomID` 函式對應的 HTTP 要求也稱為 "LoginWithCustomID"。要求本文會以索引鍵和值的形式封裝在 JavaScript 要求物件中。工作階段票證會在登入時儲存，因此用戶端呼叫不需要納入要求標頭中的工作階段票證。

* `PlayFabGettingStarted.js` 的逐行分析
  * `PlayFab.settings.titleId = "xxxx";`
    * 每位 PlayFab 開發人員都會在 Game Manager 中建立遊戲。當您發佈遊戲時，必須將該 titleId 寫入遊戲程式碼中。這可讓用戶端知道如何存取 PlayFab 中正確的資料。對大多數使用者而言，只要將其視為讓 PlayFab 運作的必要步驟即可。

  * `var loginRequest = { TitleId: PlayFab.settings.titleId, CustomId: "GettingStartedGuide", CreateAccount: true };`
    * 大多數 PlayFab API 方法都需要輸入參數，而這些輸入參數會封裝在要求物件中。
    * 每個 API 方法都需要唯一的要求物件，其中包含選擇性和必要參數的組合。
      * 對於 `LoginWithCustomID`，有一個必要參數 `CustomId` 可唯一識別玩家，還有 `CreateAccount` 允許透過此呼叫建立新帳戶。`TitleId` 是 JavaScript 中的另一個必要參數，且必須與 `PlayFab.settings.titleId` 相符。
      * 如需在何處尋找 `TitleId` 的相關資訊，請參閱 [Game Manager 快速入門](/zh-TW/services/playfab/live-service-management/gamemanager/quickstart)。

  * 在此案例中，`TitleId`、`customId` 和 `CreateAccount` 來自 `LoginWithCustomID` 的要求本文。要求本文欄位會以索引鍵和值的形式納入要求物件中。要求標頭中的工作階段票證會在登入時儲存，因此 SessionTicket 不會包含在要求物件中。

  * `PlayFabClientSDK.LoginWithCustomID(loginRequest, LoginCallback);`
    * 這會開始對 `LoginWithCustomID` 的非同步要求，並在 API 呼叫完成時呼叫 `LoginCallback`。
    * 對於登入，大多數開發人員會想要使用更合適的登入方法。
      * 如需所有登入方法和輸入參數的清單，請參閱 [PlayFab 登入文件](xref:titleid.playfabapi.com.client.authentication)。常見的選擇包括：
        * [LoginWithAndroidDeviceID](xref:titleid.playfabapi.com.client.authentication.loginwithandroiddeviceid)
        * [LoginWithIOSDeviceID](xref:titleid.playfabapi.com.client.authentication.loginwithiosdeviceid)
        * [LoginWithEmailAddress](xref:titleid.playfabapi.com.client.authentication.loginwithemailaddress)

  * 如果您是 JavaScript 新手，建議您先閱讀回呼函式的相關資訊。

  * `LoginCallback` 包含兩個參數：result 和 error
    * 成功時，error 會是 null，而 result 物件會根據所呼叫的 API 包含所要求的資訊。
    * 此 result 包含玩家的一些基本資訊，但對大多數使用者而言，登入只是呼叫其他 API 之前的必要步驟。

  * 如果 error 不是 `null`，表示您的 API 呼叫已失敗。

## 疑難排解

* API 呼叫可能因許多原因而失敗，您應該一律嘗試處理失敗情況。
* error 物件包含錯誤名稱、錯誤碼和錯誤訊息。這些資訊加起來應該足以診斷您的錯誤。
* 您可以在 PlayFab 的[全域 API 方法錯誤碼](/zh-TW/services/playfab/api-references/global-api-method-error-codes)中找到全域 API 方法錯誤碼。
* API 呼叫失敗的原因 (依可能性排序)
  * 未設定 PlayFabSettings.TitleId。如果未設定 TitleId，則一切都無法運作。
  * 要求參數。如果您沒有為特定 API 呼叫提供正確或必要的資訊，呼叫就會失敗。如需詳細資訊，請參閱 `error.errorMessage, error.errorDetails` 或 `error.GenerateErrorReport()`。
  * 裝置連線問題。行動電話會不斷失去/恢復連線，因此任何 API 呼叫都可能隨時隨機失敗，然後又立即恢復正常。進入隧道可能會讓您完全中斷連線。
* PlayFab 伺服器問題。就像所有軟體一樣，可能會發生問題。如需更新資訊，請參閱我們的[版本資訊](/zh-TW/services/playfab/release-notes)。
  * 網際網路並非 100% 可靠。有時訊息會損毀或無法送達 PlayFab 伺服器。
* 如果您在偵錯問題時遇到困難，而錯誤資訊中的內容又不足夠，請造訪我們的[論壇](https://community.playfab.com/index.html)。

## 後續步驟

本快速入門示範了驗證使用者的簡化程序。如需使用者驗證的其他資訊，請參閱[登入基本概念和最佳做法](/zh-TW/services/playfab/identity/player-identity/login/login-basics-best-practices)。

祝您程式撰寫愉快！


## Related topics

- [適用於原生與 Android Studio 的 Java 快速入門](/zh-TW/services/playfab/sdks/java/quickstart.md)
- [適用於 Windows 的 C++ 快速入門](/zh-TW/services/playfab/sdks/playfab-cpp/quickstart-windows.md)
- [適用於 Linux 的 C++ 快速入門](/zh-TW/services/playfab/sdks/playfab-cpp/quickstart-linux.md)
- [適用於 GDK 的 C/C++ 快速入門](/zh-TW/services/playfab/sdks/playfab-cpp/quickstart-gdk.md)
- [適用於 Postman 的 PlayFab REST API 集合快速入門](/zh-TW/services/playfab/sdks/postman/postman-quickstart.md)