빠른 시작: JavaScript용 PlayFab 클라이언트 라이브러리

아티클
07/11/2023

플레이어를 인증하기 위한 JavaScript용 PlayFab 클라이언트 라이브러리를 시작합니다. 단계에 따라 패키지를 설치하고 예제 코드를 통해 기본 작업을 수행해 봅니다.

필수 조건

PlayFab 개발자 계정 타이틀을 만들고 TitleId를 찾는 방법에 대한 자세한 내용은 게임 관리자 빠른 시작을 참조하세요.

이 빠른 시작 가이드는 웹 브라우저를 실행할 수 있는 모든 운영 체제에 적용됩니다.

JavaScript 프로젝트 설정

PlayFab API를 호출하려면 먼저 PlayFab 개발자 계정이 있어야 합니다. 타이틀을 만들고 TitleId를 찾는 방법에 대한 자세한 내용은 게임 관리자 빠른 시작을 참조하세요.

OS: 이 가이드는 웹 브라우저를 실행할 수 있는 모든 OS에 적용됩니다.

새 프로젝트를 설정하려면 다음 두 개의 빈 텍스트 파일이 있는 새 폴더를 만듭니다.

PlayFabGettingStarted.html
PlayFabGettingStarted.js

이것으로 PlayFab 설치가 완료되었습니다.

코드 예제

이 가이드에서는 첫 번째 PlayFab API 호출을 만들기 위한 최소 단계를 제공합니다. 웹 페이지에 확인이 표시됩니다. 매개 변수 및 반환 값을 자세히 알아보려면 먼저 Postman 템플릿을 사용하는 것이 좋습니다.

클라이언트 인증

원하는 텍스트 편집기에서 PlayFabGettingStarted.html의 내용을 다음과 같이 업데이트합니다.

<!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의 내용을 다음과 같이 업데이트합니다.

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에 대한 API 참조를 확인하세요.

코드 실행

원하는 브라우저에서 PlayFabGettingStarted.html을 엽니다.
Call LoginWithCustomID(LoginWithCustomID 호출) 단추를 클릭합니다.
결과 섹션에 “Congratulations, you made your first successful API call!”(축하합니다. 첫 번째 API 호출을 만들었습니다.)이라는 텍스트가 표시됩니다.

이제 다른 API 호출을 만들고 게임 빌드를 시작할 수 있습니다.

사용 가능한 모든 클라이언트 API 호출 목록을 보려면 PlayFab API 참조 설명서를 참조하세요.

코드 분해

이 섹션에서는 코드의 각 부분을 자세히 설명합니다.

HTML 파일에는 몇 가지 중요한 줄이 있습니다.

<script type="text/javascript" src="https://download.playfab.com/PlayFabClientApi.js"></script>

이 줄은 PlayFab CDN에서 직접 클라이언트 SDK를 로드합니다. PlayFab CDN에서는 항상 최신 버전의 PlayFabSDK를 호스트합니다. 파일을 다운로드하고 최종 버전인 PlayFab JavaScript SDK를 사용하는 것이 안전합니다.

<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 개발자는 게임 관리자에서 타이들을 만듭니다. 게임을 게시할 때 게임에 해당 titleId를 코딩해야 합니다. 이렇게 하면 클라이언트가 PlayFab 내에서 올바른 데이터에 액세스하는 방법을 알 수 있습니다. 대부분의 사용자는 이를 PlayFab을 작동하게 하는 필수 단계로 보면 됩니다.
- var loginRequest = { TitleId: PlayFab.settings.titleId, CustomId: "GettingStartedGuide", CreateAccount: true };
  - 대부분의 PlayFab API 메서드에는 입력 매개 변수가 필요하고 이러한 입력 매개 변수는 요청 개체로 압축됩니다.
  - 모든 API 메서드는 선택적 매개 변수와 필수 매개 변수가 혼합된 고유 요청 개체가 필요합니다.
    - LoginWithCustomID의 경우, 플레이어와 CreateAccount를 고유하게 식별하는 CustomId라는 필수 매개 변수가 있어 이 호출로 새로운 계정을 생성하도록 합니다. TitleId은 JavaScript의 또 다른 필수 매개 변수며 PlayFab.settings.titleId과(와) 일치해야 합니다.
    - TitleId를 확인할 수 있는 위치에 대한 자세한 내용은 게임 관리자 빠른 시작을 참조하세요.
- 이 경우 TitleId, customId 및 CreateAccount은(는) LoginWithCustomID의 요청 본문에 있습니다. 요청 본문 필드는 요청 개체에 키 및 값으로 포함됩니다. 요청 헤더의 세션 티켓은 로그인할 때부터 저장되므로 SessionTicket은 요청 개체에 포함되지 않습니다.
- PlayFabClientSDK.LoginWithCustomID(loginRequest, LoginCallback);
  - 이 줄은 LoginWithCustomID에 대한 비동기 요청을 시작하며, 해당 요청은 API 호출이 완료되면 LoginCallback을 호출합니다.
  - 로그인의 경우 대부분의 개발자는 보다 적절한 로그인 메서드를 사용하려고 합니다.
    - 모든 로그인 메서드 및 입력 매개 변수 목록은 PlayFab 로그인 설명서를 참조하세요. 일반적인 옵션은 다음과 같습니다.
- JavaScript를 처음 사용하는 개발자는 콜백 함수에 대해 알아보는 것이 좋습니다.
- LoginCallback는 result, error의 두 가지 매개 변수를 포함합니다.
  - 호출에 성공하면 error는 null이 되며, result 개체는 호출된 API에 따라 요청된 정보를 포함합니다.
  - 이 결과에는 플레이어에 대한 몇 가지 기본 정보가 포함되지만 대부분의 사용자에게는 다른 API를 호출하기 전 필수 단계는 로그인뿐입니다.
- 오류가 null이 아니면 API 호출이 실패한 것입니다.

문제 해결

API 호출은 여러 가지 이유로 실패할 수 있으며, 항상 실패 처리를 시도해야 합니다.
오류 개체에는 오류 이름, 오류 코드, 오류 메시지가 포함됩니다. 이 전체 정보가 충분해서 오류를 진단할 수 있습니다.
글로벌 API 메서드 오류 코드는 PlayFab의 글로벌 API 메서드 오류 코드에서 확인할 수 있습니다.
API 호출이 실패하는 이유(가능성이 높은 순서대로 나열)
- PlayFabSettings.TitleId가 설정되지 않았습니다. TitleId가 설정되지 않으면 아무것도 작동하지 않습니다.
- 매개 변수를 요청합니다. 특정 API 호출에 대해 정확한 또는 필요한 정보를 제공하지 않은 경우 호출에 실패합니다. 자세한 내용은 error.errorMessage, error.errorDetails 또는 error.GenerateErrorReport()를 참조하세요.
- 디바이스 연결 문제입니다. 휴대폰은 지속적으로 연결이 끊어졌다가 다시 연결되므로 언제든지 모든 API 호출이 실패한 후 바로 다시 작동할 수 있습니다. 터널로 들어가면 연결이 완전히 끊길 수 있습니다.
PlayFab 서버 문제. 모든 소프트웨어와 마찬가지로 문제가 있을 수 있습니다. 업데이트에 대해서는 릴리스 정보를 참조하세요.
- 인터넷은 100% 신뢰할 수 없습니다. 때때로 메시지가 손상되었거나 PlayFab 서버에 연결되지 않을 수 있습니다.
문제를 디버깅하는 데 문제가 있는 경우 오류 정보 내의 정보로는 충분하지 않습니다. 포럼에서 문의해 주시기 바랍니다.

다음 단계

이 빠른 시작에서는 사용자를 인증하기 위한 간단한 절차를 보여 줍니다. 사용자 인증에 대한 자세한 내용은 로그인 기본 사항 및 모범 사례를 참조하세요.

즐거운 코딩이 되시길 바랍니다.

다음을 통해 공유