엔터프라이즈급 Unity용 SDK / 페이 스테이션을 PlayFab 인증과 함께 사용하는 방법
  문서로 돌아가기

엔터프라이즈급 Unity용 SDK

페이 스테이션을 PlayFab 인증과 함께 사용하는 방법

애플리케이션에서 PlayFab을 사용하여 사용자 인증을 이미 구현한 경우 PlayFab에서 결제 토큰을 생성한 다음 이를 애플리케이션의 클라이언트 측에 전달하여 결제 UI를 열 수 있습니다.

이 연동 옵션을 사용하는 경우 구매 시 비용을 지불하는 사용자의 국가 및 통화를 결정하는 로직을 독립적으로 구현해야 합니다.

연동 절차:

  1. 프로젝트를 생성합니다.
  1. 관리자 페이지에 등록한 후 새 프로젝트를 생성합니다. 이후 단계에서 생성하는 프로젝트의 ID가 필요합니다.

  1. 카탈로그 설정 방법:
    • 엑솔라 측에서 아이템 카탈로그를 생성합니다. 아이템을 수동으로 추가하거나 Google Play 또는 PlayFab에서 가져올 수 있습니다.
    • SDK를 사용하여 애플리케이션의 클라이언트 측에서 카탈로그 가져오기 및 표시를 구현합니다.

  1. 아이템 구매 설정 방법:
    • PlayFab 클라우드 스크립트를 사용하여 애플리케이션의 클라이언트 측에서 사용자 및 아이템 데이터로 주문을 생성합니다.
    • SDK를 사용하여 애플리케이션의 클라이언트 측에서 결제 UI 열기를 구현합니다.

  1. 주문 상태 추적을 설정합니다.

주의

연동을 완료하고 실제 결제 수락을 시작하려면 엑솔라와 라이선스 계약을 체결해야 합니다.

모든 연동 단계에서 라이선스 계약에 서명할 수 있지만, 검토 절차에 최대 3일(영업일 기준)이 소요될 수 있다는 점에 유의해 주세요.

프로젝트 생성

관리자 페이지에 등록하기

관리자 페이지는 엑솔라 기능을 구성하고 분석과 트랜잭션 작업에 사용하는 기본 도구입니다.

등록할 때 지정한 회사 및 애플리케이션에 대한 데이터는 엑솔라와의 라이선스 계약 초안을 생성하고 적합한 솔루션 추천을 생성하는 데 사용됩니다. 나중에 해당 데이터를 변경할 수 있지만 등록할 때 올바른 데이터를 제공하면 라이선스 계약 체결 프로세스가 빨라집니다.

등록하려면 관리자 페이지로 이동한 후 계정을 생성합니다.

알림

관리자 페이지의 암호는 라틴 문자, 숫자 및 특수 문자로 구성될 수 있으며 다음 최소 요건을 충족해야 합니다.

  • 8자 이상
  • 숫자 하나 이상
  • 대문자 하나 이상
  • 소문자 하나 이상

암호 보안을 위해 다음을 권장합니다.

  • 90일에 한 번 이상 암호 변경
  • 기존 계정 암호에 사용한 마지막 4개의 문자와 일치하지 않는 새 암호 사용
  • 다른 곳에서 사용하는 암호와 일치하지 않는 고유한 암호 사용
  • 쉽게 액세스할 수 없는 곳에 암호 저장
  • 암호 관리 프로그램을 사용하여 암호 저장

관리자 페이지는 2단계 인증을 사용하며 인증을 시도할 때마다 확인 코드를 전송합니다.

관리자 페이지에서 프로젝트 생성

애플리케이션이 여러 개 있는 경우 각 애플리케이션에 대한 별도의 프로젝트를 생성하는 것이 좋습니다. 프로젝트 생성 시 지정한 데이터를 기반으로 엑솔라는 적합한 솔루션에 대한 권장 사항을 생성합니다.

새 프로젝트를 생성하는 방법:

  1. 관리자 페이지를 엽니다.
  2. 사이드 메뉴에서 새 프로젝트 만들기를 클릭합니다.

  1. 프로젝트 이름을 영문으로 입력합니다(필수).

알림
프로젝트를 생성한 후 프로젝트 설정 섹션에서 추가 언어와 현지화된 프로젝트 이름을 추가할 수 있습니다.

  1. 게임을 출시하는 플랫폼을 하나 또는 여러 개 선택합니다(필수).
  2. 게임 링크를 추가합니다. 게임에 아직 웹사이트가 없는 경우 게임에 대한 정보가 포함된 소스 링크를 추가합니다(필수).
  3. 게임 엔진을 선택합니다.
  4. 사용 중이거나 사용할 예정인 수익화 옵션을 선택합니다.
  5. 게임이 이미 출시되었는지 여부를 지정합니다. 게임이 아직 출시되지 않은 경우 출시 예정일을 지정합니다.
  6. 프로젝트 생성을 클릭합니다. 추천하는 엑솔라 제품이 있는 페이지가 표시됩니다.

연동을 처리하는 동안 프로젝트 이름 옆의 관리자 페이지에서 확인할 수 있는 프로젝트 ID를 제공해야 합니다.

카탈로그 설정하기

관리자 페이지에서 아이템 생성하기

주의

엑솔라 측에서 카탈로그를 생성해야 합니다. 아이템 수동으로 추가하기Google Play 또는 PlayFab에서 가져오기를 수행할 수 있습니다. Google Play에서 가져오기를 수행할 경우 한 번에 최대 100개의 아이템을 가져올 수 있습니다.

이 지침은 가상 아이템의 기본 설정 단계를 제공합니다. 나중에 카탈로그에 다른 아이템(인게임 재화, 번들, 게임 키)을 추가하고, 아이템 그룹을 생성하고, 프로모션 캠페인, 지역별 가격 등을 설정할 수 있습니다.

카탈로그에 기본 설정이 있는 가상 아이템을 추가하는 방법:

  1. 관리자 페이지에서 프로젝트를 엽니다.
  2. 사이드 메뉴에서 스토어를 클릭합니다.
  3. 가상 아이템 창에서 연결을 클릭합니다.
  4. 드롭다운 메뉴에서 아이템 생성을 선택합니다.

  1. 다음 필드에서 아이템의 기본 설정을 설정합니다.
    • 이미지(선택 사항)
    • SKU(아이템 고유 ID)
    • 아이템 이름
    • 설명(선택 사항)

  1. 아이템 가격 지정:
    1. 실제 통화 가격 토글을 으로 설정합니다.
    2. 기본 통화 필드에서 통화를 변경하고(선택 사항) 아이템 가격을 지정합니다.
    3. 기본 통화 필드에서 통화를 변경한 경우 실제 통화 가격 필드에서 동일한 통화를 선택합니다.

알림
카탈로그를 가져오는 API 호출이 올바르게 작동되도록 하려면 모든 아이템에 대해 기본 통화와 가격이 지정된 통화 목록이 일치하는지 확인합니다.

  1. 아이템 상태를 사용 가능으로 변경합니다.

  1. 아이템 생성을 클릭합니다.

애플리케이션의 클라이언트 측에 카탈로그 표시하기

  1. CDN 또는 GitHub에서 SDK를 다운로드합니다.
  2. 패키지의 압축을 해제합니다.
  3. 메인 메뉴에서 Assets > Import Package > Custom Package로 이동한 후 다운로드한 SDK를 선택합니다.
  4. 메인 메뉴에서 Window > Xsolla > Edit Settings로 이동합니다.
  5. Inspector 패널로 이동합니다. Project ID 필드에서 프로젝트 이름 옆에 관리자 페이지에서 확인할 수 있는 프로젝트 ID를 지정합니다.

  1. 애플리케이션의 클라이언트 측에서 제품 카탈로그를 표시하는 UI를 추가합니다.
  2. 엑솔라 서버로부터 아이템 카탈로그를 요청하는 기능을 구현합니다.

알림

가상 아이템 목록을 가져오려면 GetCatalog SDK 메소드를 사용합니다. 다른 SDK 메소드를 사용하여 카탈로그 아이템에 대한 정보를 가져올 수도 있습니다.

카탈로그 페이지 생성에 대한 단계별 튜토리얼은 아이템 카탈로그 표시를 참조해 주세요.

아이템 구매 설정하기

엑솔라 측에서 사용자 및 아이템 데이터로 주문을 생성하려면 구매용 결제 토큰 생성 API 호출을 사용하는 클라우드 함수를 프로젝트에 추가합니다. 이 호출은 결제 UI를 열고 구매를 하는 데 필요한 결제 토큰을 반환합니다.

제한 사항:

  • 결제 토큰을 요청할 때 사용자 국가 또는 사용자의 IP 주소를 전달해야 합니다.
  • 토큰에서 통화를 전달하지 않으면 국가에 따라 결정됩니다.
  • 토큰에서 통화를 전달하면 사용자가 이 통화로 결제합니다.

알림

PlayFab 프로젝트가 생성되어 있고, PlayFab SDK가 이미 유니티 프로젝트에 연동되어 있어야 합니다.

PlayFab 클라우드 스크립트는 HTTP 트리거 함수를 직접 지원하지 않으므로 Azure 함수가 웹훅 수신 구현에 사용됩니다.

Azure 함수를 시작하려면 Azure 계정을 생성하고 개발 환경을 준비합니다. 이 지침에서는 다음과 같은 설정의 개발 환경에서 단계를 설명합니다.

프로젝트에 클라우드 스크립트 추가하기

  1. Visual Studio Code를 열고 Azure 탭으로 이동합니다.
  2. Workspace 섹션에서 + 아이콘을 클릭한 후 Create Function을 선택합니다.

  1. 새 프로젝트 디렉터리를 선택합니다. 설정 선택과 함께 새 프로젝트를 생성하는 메뉴가 나타납니다.

  1. 새 프로젝트 설정 지정 방법:
    1. 함수 프로젝트 언어로 C#을 선택합니다.
    2. .NET 런타임으로 .NET 8.0 Isolated (LTS)를 선택합니다.
    3. 프로젝트의 첫 번째 함수 템플릿으로 HTTP trigger를 선택합니다.
    4. 함수 이름으로 GetXsollaPaymentToken을 입력합니다.
    5. 네임스페이스를 My.Functions를 입력합니다.
    6. 인증 수준을 Anonymous로 선택합니다.
    7. 프로젝트 열기 방식을 Open in current window로 선택합니다.

  1. 그러면 Visual Studio Code가 C# 프로젝트를 생성하고 생성된 GetXsollaPaymentToken.cs 파일을 엽니다.

  1. GetXsollaPaymentToken.cs 파일 수정 방법:

Copy
Full screen
Small screen
using System.Text;
using System.Net.Http.Headers;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;

namespace My.Function
{
    public class GetXsollaPaymentToken
    {
        private readonly ILogger<GetXsollaPaymentToken> _logger;

        private const int PROJECT_ID = ""; // Your Xsolla project ID
        private const string API_KEY = ""; // Your Xsolla API key

        public GetXsollaPaymentToken(ILogger<GetXsollaPaymentToken> logger)
        {
            _logger = logger;
        }

        [Function("GetXsollaPaymentToken")]
        public async Task<IActionResult> Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req)
        {
            _logger.LogInformation("GetXsollaPaymentToken function processed a request.");

            // Reading the request body
            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            _logger.LogInformation("Request body: " + requestBody);

            // Deserializing request body JSON
            dynamic data = JsonConvert.DeserializeObject(requestBody);

            // Extracting necessary data from JSON
            string uid = data.FunctionArgument.uid;
            string sku = data.FunctionArgument.sku;
            string returnUrl = data.FunctionArgument.returnUrl;

            // Creating payload for Xsolla API
            var payload = new
            {
                user = new
                {
                    id = new { value = uid },
                    country = new { value = "US", allow_modify = false }
                },
                purchase = new
                {
                    items = new[]
                    {
                        new { sku = sku, quantity = 1 }
                    }
                },
                sandbox = true,
                settings = new
                {
                    language = "en",
                    currency = "USD",
                    return_url = returnUrl,
                    ui = new { theme = "63295aab2e47fab76f7708e3" }
                }
            };

            // Constructing Xsolla API URL
            string url = $"https://store.xsolla.com/api/v3/project/{PROJECT_ID}/admin/payment/token";

            // Sending request to Xsolla API
            using (HttpClient client = new HttpClient())
            {
                // Adding authorization header
                string headerValue = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{PROJECT_ID}:{API_KEY}"));
                client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", headerValue);

                // Serializing payload to JSON
                var jsonPayload = JsonConvert.SerializeObject(payload);
                var content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");

                // Making POST request to Xsolla API
                var xsollaRes = await client.PostAsync(url, content);

                // Checking response from Xsolla API
                if (xsollaRes.IsSuccessStatusCode)
                {
                    // Reading successful response content
                    string responseContent = await xsollaRes.Content.ReadAsStringAsync();
                    return new OkObjectResult(responseContent);
                }
                else
                {
                    // Returning status code in case of failure
                    return new StatusCodeResult((int)xsollaRes.StatusCode);
                }
            }
        }
    }
}

  1. 스크립트에서 상수 값을 지정합니다.

    • PROJECT_ID - 프로젝트 이름 옆의 관리자 페이지에서 확인할 수 있는 프로젝트 ID입니다.

    • API_KEY - API 키입니다. 생성할 때 한 번만 관리자 페이지에 표시되며 따로 저장하고 관리해야 합니다. 다음 섹션에서 새 키를 생성할 수 있습니다.
      • 회사 설정 > API 키
      • 프로젝트 설정 > API 키

클라우드 스크립트를 추가한 후 로컬에서 GetXsollaPaymentToken 함수의 호출을 테스트할 수 있습니다.

클라우드 스크립트 배포

  1. Visual Studio Code에서 Azure > Resources 섹션으로 이동한 후 + 아이콘을 클릭합니다.
  2. 리소스로 Create Function App in Azure를 선택합니다. 설정 선택과 함께 새 애플리케이션을 생성하는 메뉴가 나타납니다.
  3. 애플리케이션 설정을 설정하는 방법:

    1. 새 함수 이름을 XsollaFunctions로 입력합니다.
    2. 런타입 스택으로 .NET 8 Isolated를 선택합니다.
    3. 새 리소스의 위치를 선택합니다(원하는 옵션 선택 가능).

  1. 리소스 그룹이 생성될 때까지 기다립니다.

  1. 리소스 목록에서 XsollaFunctions를 선택하고 컨텍스트 메뉴를 호출한 후 Deply to Function App을 선택합니다.

클라우드 스크립트를 추가한 후 원격으로 GetXsollaPaymentToken 함수의 호출을 테스트할 수 있습니다.

클라우드 스크립트 테스트

클라우드 스크립트를 로컬 또는 원격으로 테스트하려면 Postman 또는 다른 도구를 사용하여 GetXsollaPaymentToken 함수를 호출합니다. 수행 방법:

  1. Visual Studio Code에서 Azure > Workspace > Local Project > Functions 섹션으로 이동한 후 Start debugging to update this list를 클릭합니다.
  2. 함수의 컨텍스트 메뉴를 호출한 후 Copy Function Url을 선택합니다. 로컬에서 테스트하는 경우 URL은 http://localhost:7071/api/getXsollaPaymentToken와 같이 표시됩니다. 원격으로 테스트하는 경우에는 https://xsollafunctions.azurewebsites.net/api/GetXsollaPaymentToken으로 표시됩니다.

  1. 복사한 URL을 사용하여 지정된 매개 변수로 함수를 호출합니다. Postman에서 함수를 호출하는 방법:
    1. GET 요청을 생성합니다.
    2. 2단계에서 복사한 URL을 제공합니다.
    3. Body 탭으로 이동하여 요청 매개 변수를 지정합니다.

요청 본문 예시:

Copy
Full screen
Small screen
{

 "FunctionArgument": {

   "uid": "1D384D9EF12EAB8B",

   "sku": "booster_max_1",

   "returnUrl": "https://login.xsolla.com/api/blank"

 }

}
알림
사용자 ID(uid)에는 아무 값이나 지정할 수 있습니다. 아이템 SKU(sku)로 이전에 관리자 페이지에서 추가한 가상 아이템의 SKU를 지정합니다.

  1. Send를 클릭합니다. 응답으로 다음 매개 변수와 함께 JSON을 수신해야 합니다.
    • token - 결제 토큰입니다. 결제 UI를 열 때 필요합니다.
    • order_id - 생성된 주문의 ID입니다. 주문 상태를 추적할 때 필요합니다.

응답 본문 예시:

Copy
Full screen
Small screen
{"token":"xsnpCF8tS4ox7quoibgTgPFVFxG9gTvS_lc_en_bg_2C2640_tb_6E7BF7","order_id":90288613}

PlayFab에서 결제 토큰을 받는 함수 등록하기

  1. PlayFab에서 프로젝트를 엽니다.
  2. 사이드 메뉴에서 Automation을 클릭합니다.
  3. Register New Cloud Script Function 섹션에서 Register Function을 클릭합니다.
  4. 함수 이름으로 GetXsollaPaymentToken을 입력합니다.
  5. Visual Code Studio로 복사한 함수 URL을 입력합니다(클라우드 스크립트 테스트의 1-2단계 참조).

Unity 프로젝트에서 주문 생성하고 결제 UI 열기

  1. 유니티 프로젝트를 엽니다.
  2. 다음 내용을 사용하여 XsollaPlayfabSample.cs 스크립트를 생성합니다.

Copy
Full screen
Small screen
using System;
using PlayFab;
using PlayFab.ClientModels;
using PlayFab.CloudScriptModels;
using UnityEngine;
using Xsolla.Core;

public class XsollaPlayfabSample : MonoBehaviour
{
    private void Start()
    {
        // Logging in anonymously
        LoginAnonymous(
            // Callback function invoked after successful login
            userId => {
                // Requesting Xsolla payment token
                GetXsollaPaymentToken(
                    userId, // PlayFab user ID received after login
                    "booster_max_1", // SKU of the product
                    orderData => {
                        // Creating Xsolla token and opening purchase UI
                        XsollaToken.Create(orderData.token);
                        XsollaWebBrowser.OpenPurchaseUI(orderData.token);

                        // Adding order for tracking
                        OrderTrackingService.AddOrderForTracking(
                            orderData.order_id,
                            true,
                            () => Debug.Log("Payment completed"),
                            onError => Debug.LogError(onError.errorMessage));
                    });
            });
    }

    private static void LoginAnonymous(Action<string> onSuccess)
    {
        // Logging in with custom ID
        PlayFabClientAPI.LoginWithCustomID(
            new LoginWithCustomIDRequest {
                CustomId = SystemInfo.deviceUniqueIdentifier, // Unique ID generated based on the device
                CreateAccount = true
            },
            result => {
                // Logging the result
                Debug.Log("Logged with playfab id: " + result.PlayFabId);

                // Invoking onSuccess callback with PlayFab ID
                onSuccess?.Invoke(result.PlayFabId);
            },
            error => { Debug.LogError(error.GenerateErrorReport()); }); // Handling login error
    }

    private static void GetXsollaPaymentToken(string userId, string sku, Action<OrderData> onSuccess)
    {
        // Creating request data for Xsolla payment token
        var tokenRequestData = new PaymentTokenRequestData {
            uid = userId, // User ID
            sku = sku, // Product SKU
            returnUrl = $"app://xpayment.{Application.identifier}" // Return URL
        };

        // Executing a function in the PlayFab cloud to get payment token
        PlayFabCloudScriptAPI.ExecuteFunction(
            new ExecuteFunctionRequest {
                FunctionName = "GetXsollaPaymentToken", // Name of Azure function
                FunctionParameter = tokenRequestData, // Data passed to the function
                GeneratePlayStreamEvent = false // Setting true if call should show up in PlayStream
            },
            result => {
                // Logging the result
                Debug.Log($"GetXsollaPaymentToken result: {result.FunctionResult}");

                // Parsing JSON result to OrderData object
                OrderData orderData = JsonUtility.FromJson<OrderData>(result.FunctionResult.ToString());

                // Invoking onSuccess callback with order data
                onSuccess?.Invoke(orderData);
            },
            error => Debug.LogError($"Error: {error.GenerateErrorReport()}")); // Handling error
    }

    // Class for payment token request data
    public class PaymentTokenRequestData
    {
        public string uid; // User ID
        public string sku; // Product SKU
        public string returnUrl; // Return URL
    }
}

  1. 새 장면을 생성합니다.
  2. 게임 개체를 생성합니다. 이렇게 하려면 메인 메뉴로 이동하여 GameObject > Create Empty를 선택합니다.

  1. 게임 개체에 스크립트 추가하기:
    1. Hierarchy 패널에서 개체를 선택합니다.
    2. Inspector 패널에서 Add Component를 클릭한 후 XsollaPlayfabSample 스크립트를 선택합니다.

  1. Hierarchy 패널에서 컨텍스트 메뉴를 호출한 후 UI > EventSystem을 선택합니다.

주문 생성을 테스트하려면 Play를 클릭하여 장면을 실행합니다. 그러면 주문 정보와 함께 결제 UI가 표시되어야 합니다.

유니티 프로젝트의 소스 코드는 GitHub에서 확인할 수 있습니다.

주문 상태 추적 설정하기

주문 상태 추적은 결제가 성공적으로 이루어졌는지 확인하고 사용자에게 아이템을 제공할 때 필요합니다.

클라이언트 측에서 주문 상태 가져오기

주문 추적 로직은 GetXsollaPaymentToken 메소드에 포함되어 있습니다. 성공적으로 구매를 처리하려면 주문 상태가 done으로 변경될 때 호출되는 함수를 전달해야 합니다.

추적에는 AddOrderForTracking SDK 메소드가 사용됩니다. 메소드 작동 방식에 대한 자세한 내용은 주문 상태 추적을 참조해 주세요.

서버 측에서 주문 상태 가져오기

주의

SDK를 사용하면 애플리케이션의 클라이언트 측에서 주문 상태를 추적할 수 있습니다. 다만 애플리케이션의 백엔드에서 주문 정보를 수신하도록 결제 웹훅 핸들러를 설정하는 것이 좋습니다. 이렇게 하면 완료된 구매에 대한 추가 유효성 검사를 구현할 수 있습니다.

웹훅의 전체 목록과 웹훅 작업에 대한 일반적인 정보는 웹훅 문서를 참조해 주세요.

엑솔라 측에서 웹훅을 구성하는 방법:

  1. 관리자 페이지에서 프로젝트를 엽니다.
  2. 사이드 메뉴에서 프로젝트 설정을 클릭하고 웹훅 섹션으로 이동합니다.
  3. 웹훅 서버 필드에서 엑솔라가 웹훅을 전송할 URL을 입력합니다.

알림

웹훅을 테스트하기 위해 webhook.site와 같은 전용 사이트나 ngrok과 같은 플랫폼을 선택할 수도 있습니다.

테스트 목적으로 성공적인 웹훅 처리를 시뮬레이션하는 클라우드 스크립트를 추가할 수도 있습니다. 스크립트 코드는 GitHub에서 확인할 수 있습니다.

실제 프로젝트에서는 구매 유효성 검사 로직을 추가해야 합니다.

  1. 비밀 키 필드의 값을 복사하여 저장합니다. 이 키는 기본값으로 생성되며 웹훅 서명에 사용됩니다. 변경하려면 업데이트 아이콘을 클릭합니다.
  2. 웹훅 사용을 클릭합니다.

이 기사가 도움이 되었나요?
감사합니다!
개선해야 할 점이 있을까요? 메시지
유감입니다
이 기사가 도움이 안 된 이유를 설명해 주세요. 메시지
의견을 보내 주셔서 감사드립니다!
메시지를 검토한 후 사용자 경험 향상에 사용하겠습니다.
마지막 업데이트: 2024년 10월 3일

오자 또는 기타 텍스트 오류를 찾으셨나요? 텍스트를 선택하고 컨트롤+엔터를 누르세요.

문제 보고
콘텐츠를 항상 검토합니다. 여러분의 피드백은 콘텐츠를 개선에 도움이 됩니다.
후속 조치를 위해 이메일을 제공해 주세요
의견을 보내 주셔서 감사드립니다!