Xsolla Documentation

Buy Button은 디지털 상품 판매에 포괄적으로 사용할 수 있는 솔루션입니다.

Note: 엑솔라 제품을 이미 사용하고 있고 Buy Button을 통합하기 원할 경우, 계정 관리자에게 문의하십시오.

작동 방식

1 단계

2 단계

3 단계

사용자 플로우

통합 절차

Buy Button 통합 방법:

엑솔라 게사자 계정을 등록합니다.
프로젝트를 생성합니다.
현금화 옵션을 선택합니다.
아이템 판매 옵션을 선택합니다.

Note: 본 가이드에는 솔루션을 빠르게 시작하기 위해 필요한 최소 설정에 대한 설명이 제공되어 있습니다. 질문이 있을 경우, 계정 관리자에게 문의하십시오.

프로젝트 생성

프로젝트로 이동하고 새 프로젝트 만들기를 클릭합니다.
설정 모드에서:
1. 웹훅 URL을 지정합니다.
2. 프로젝트 웹훅에 서명할 비밀 키를 생성합니다.

현금화 옵션

가상 머니

게임 개발자는 가상 화폐 옵션을 사용하여 인게임 통화를 판매할 수 있습니다. 주요 기능:

인게임 통화 패키지 판매
프로모션 캠페인 실행
인게임 통화 사용자 잔액 관리
사용자 통화 및 국가 자동 감지

설정

가상 화폐 설정으로 이동하여 다음 매개변수를 구성합니다.
- 이름
- 단위당 가격
- 이미지
가상 화폐 패키지를 필요한만큼 생성하고 각 패키지를 위해 다음과 같은 매개변수를 설정합니다.
- 가격
- 이미지
스토어에서 패키지 디스플레이를 켭니다.

웹훅 설정

가상 화폐의 경우 다음과 같은 웹훅을 구현해야 합니다.

메시지 본문 없이 HTTP 코드 204로 응답하여 웹훅을 수신하였음을 확인합니다. API 레퍼런스에서 예제를 비롯해 웹훅에 대해 자세히 알아볼 수 있습니다.

웹훅 핸들러를 테스트하려면 프로젝트 설정 > 웹훅 섹션을 여십시오.

레시피

당사 레시피는 가상 화폐에 대한 일부 고급 기능을 시도해볼 수 있도록 지원합니다.

가상 아이템

가상 아이템 옵션을 사용하여 실제 또는 가상 통화로 인게임 콘텐츠를 판매할 수 있습니다. 주요 기능:

실제 및 가상 통화로 가격 설정
하나 또는 여러 개의 레벨로 카탈로그 설정
콘텐츠 액세스 관리. 예를 들어, 특정 레벨에 도달한 사용자만 특정 아이템을 사용할 수 있도록 설정할 수 있습니다.
간단하고 세부적인 아이템 카드 구성
프로모션 캠페인 실행
인게임 통화 사용자 잔액 관리
사용자 통화 및 국가 자동 감지

설정

가상 아이템 설정으로 이동합니다.
스토어 카탈로그 입력:
1. 아이템 그룹 생성.
2. 아이템을 생성하고 각각의 아이템에 대해 다음을 지정합니다:
  - 아이템이 속할 한 개 이상의 그룹
  - SKU
  - 이름 및 간단한 설명
  - 실제 및 가상 통화로 표시된 가격
  - 이미지
스토어에서 그룹 디스플레이를 켭니다.

웹훅 설정

가상 아이템의 경우 다음과 같은 웹훅을 구현해야 합니다.

메시지 본문 없이 HTTP 코드 204로 응답하여 웹훅을 수신하였음을 확인합니다. API 레퍼런스에서 예제를 비롯해 웹훅에 대해 자세히 알아볼 수 있습니다.

웹훅 핸들러를 테스트하려면 프로젝트 설정 > 웹훅 섹션을 여십시오.

레시피

당사 레시피는 가상 아이템에 대한 일부 고급 기능을 시도해볼 수 있도록 지원합니다.

게임 키

개발자는 게임 키 옵션을 통해 게임 웹 사이트에서 직접 키와 분배 패키지를 판매할 수 있습니다. 사용자는 게임 키 위젯을 사용하여 상점에 액세스할 수 있습니다. 주요 기능:

분배 키 및 분배 패키지를 통해 DRM 플랫폼 선택
개별 DRM 플랫폼을 위한 운영 체제/게임 콘솔 버전 선택
각 DRM 플랫폼에 다른 가격 설정
위젯 크기와 컬러 테마 구성
개발자에게 팁 지급
선주문

기본 또는 고급 모드로 옵션을 통합할 수 있습니다.

기본 통합

기본 통합:

빠르게 구현할 수 있으며,
토큰 생성이나 서버 구현을 요구하지 않고
사용자 사전 승인을 요구하지 않는 게임에 적합합니다.

통합하려면 프로젝트 ID 매개변수가 필요합니다. 프로젝트 설정 > 웹훅에서 확인할 수 있습니다.

모듈 설정:

프로젝트 설정 > 통합 설정에서 토큰 없이 통합 기능을 활성화합니다.
프로젝트 설정 > 웹훅에서 웹훅을 비활성화합니다.
게임 키 설정으로 이동하여 새 패키지를 누릅니다.
다음과 같은 패키지 매개변수를 구성합니다.
- SKU - 고유 식별자
- 게임 타이틀
- 게임 요약
DRM 및 플랫폼을 선택합니다.
선택한 DRM의 가격을 구성합니다.
선택한 DRM의 키를 업로드합니다.
위젯 코드를 랜딩 페이지로 구현합니다.

기본 통합에 대한 위젯 매개변수 전체 목록은 위젯을 통한 판매 섹션에서 찾아볼 수 있습니다.

고급 통합

고급 통합:

게임에서 추가 연결을 할 수 있도록 사용자 및 구매 데이터 안전하게 전송 가능
서버에서 구현하도록 설정: 토큰 생성 및 웹훅 설정

통합에 필요한 매개변수는 다음과 같습니다:

판매자 ID. 프로젝트 설정 > 웹훅에 표시
API 키. 회사 설정 > API 키에서 설정한 매개변수입니다.
프로젝트 ID. 프로젝트 설정 > 웹훅에 표시
비밀 키. 프로젝트 설정 > 웹훅에서 설정한 매개변수입니다.

모듈 설정:

게임 키로 이동하여 새 패키지를 클릭합니다.
패키지 매개변수를 구성합니다.
- SKU - 고유 식별자
- 게임 제목
- 게임에 대한 간단한 설명
DRM과 플랫폼을 선택합니다.
선택한 DRM의 가격을 구성합니다.
선택한 DRM에 대한 키를 업로드합니다.
방문 페이지에 위젯 코드를 구현합니다.

고급 통합에 사용하는 위젯 매개변수 전체 목록은 API 매개변수에서 확인할 수 있습니다.

웹훅 설정

게임 키 고급 통합 설정의 경우 다음과 같은 웹훅을 구현해야 합니다.

메시지 본문 없이 HTTP 코드 204로 응답하여 웹훅을 수신하였음을 확인합니다. API 레퍼런스에서 예제를 비롯해 웹훅에 대해 자세히 알아볼 수 있습니다.

웹훅 핸들러를 테스트하려면 프로젝트 설정 > 웹훅 섹션을 여십시오.

레시피

당사 레시피는 게임 키에 대한 일부 고급 기능을 시도해볼 수 있도록 지원합니다.

아이템 판매

직접 링크, 위젯 또는 스토어 UI를 통해 아이템을 판매할 수 있습니다.

직접 링크를 통해 판매

직접 링크는 새 창 또는 웹 사이트의 iframe에서 결제 UI를 여는 데 사용됩니다. 예: 결제 UI를 통해 웹 사이트에서 상품을 구매할 수 있도록 클릭 가능한 배너를 배치.

게임 액세스, 가상 아이템 및 가상 화폐 판매를 위한 링크 설정은 각각 다릅니다.

게임 액세스 판매

기본 통합

게임 판매를 기본 통합하는 동안에는 결제 UI를 열 때 다음 링크가 사용됩니다:

https://store.xsolla.com/pages/buy.php?type=digital_content&project_id={YOU_PROJECT_ID}&sku={YOUR-ITEM-SKU}&drm=steam

이 링크에 다음 데이터를 추가합니다.

게시자 계정의 프로젝트 ID (프로젝트 – 프로젝트 설정 – 일반 설정 – 프로젝트 ID)
아이템 SKU

추가 설정:

결제 UI 표시 – JSON 형식과 Base64 인코딩으로 이루어진 settings.ui 매개변수
DRM 사전 선택 – JSON 형식과 Base64 인코딩으로 이루어진 purchase.pin_codes.codes.drm

테스트 시 다음 URL을 사용:

https://store.xsolla.com/pages/buy.php?type=digital_content&project_id={YOU_PROJECT_ID}&sku={YOUR-ITEM-SKU}&mode=sandbox

고급 통합

게임 판매를 고급 통합하는 동안에는 결제 UI를 열 때 다음 링크가 사용됩니다:

https://store.xsolla.com/pages/buy.php?type=digital_content&project_id={YOUR_PROJECT_ID}&sku={YOUR_ITEM_SKU}&{TOKEN_TYPE}=ACCESS_TOKEN

이 링크에 다음 데이터를 추가합니다:

YOUR_PROJECT_ID – 게시자 계정의 프로젝트 ID (프로젝트 – 프로젝트 설정 – 일반 설정 – 프로젝트 ID)
YOUR_ITEM_SKU – 아이템 SKU
TOKEN_TYPE – 토큰 유형: xsolla_login_token, 엑솔라 로그인 JWT access_token, 페이 스테이션 액세스 토큰용.
ACCESS_TOKEN – 인증 유형에 따라 다르게 생성되는 토큰

테스트 시 다음 URL을 사용:

https://store.xsolla.com/pages/buy.php?access_token=ACCESS_TOKEN&mode=sandbox

가상 아이템 및 가상 화폐 판매

가상 아이템 및 가상 화폐를 판매 시 결제 UI를 열기 위해 다음 링크가 사용됩니다.

https://store.xsolla.com/pages/buy.php?type={ITEM_TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR_ITEM_SKU}&{TOKEN_TYPE}={ACCESS_TOKEN}

이 링크에 다음 데이터를 추가합니다.

아이템 유형:
- 가상 아이템 – virtual_item
- 가상 화폐 – bundle
YOUR_PROJECT_ID – 게시자 계정의 프로젝트 ID (프로젝트 – 프로젝트 설정 – 일반 설정 – 프로젝트 ID)
YOUR_ITEM_SKU – 아이템 SKU
TOKEN_TYPE – 토큰 유형: xsolla_login_token, 엑솔라 로그인 JWT용. access_token, 페이 스테이션 액세스 토큰용
ACCESS_TOKEN — 구매 데이터를 포함하고 있는 토큰

테스트 시 다음 URL을 사용:

https://store.xsolla.com/pages/buy.php?type={ITEM_TYPE}&project_id={YOUR_PROJECT_ID}&sku={YOUR_ITEM_SKU}&{TOKEN_TYPE}={ACCESS_TOKEN}&mode=sandbox

토큰 생성 방법:

구매 주문 생성을 위한 인증 토큰을 가져옵니다.
주문을 생성합니다. 결제 UI를 열기 위한 토큰이 응답으로 전달됩니다.

위젯을 통해 판매

위젯은 아이템을 판매할 수 있도록 웹 사이트에 구현하는 스크립트입니다. 위젯 작동 예시는 데모 페이지에서 확인할 수 있습니다.

Info: 위젯 설정은 프로젝트 통합 유형에 따라 달라질 수 있습니다. 통합 설정은 프로젝트 설정 > 통합 설정에서 할 수 있습니다.

위젯 구현 코드:

<script>
    var options = {
        project_id: "YOUR-PROJECT-ID",
        item_type: "YOUR-ITEM-TYPE",
        sku: "YOUR-ITEM-SKU",
        widget_ui: {
            target_element: '#widget-example-element'
        }
    };
    var s = document.createElement('script');
    s.type = "text/javascript";
    s.async = true;
    s.src = "//cdn.xsolla.net/embed/pay2play/3.0.0/widget.min.js";
    s.addEventListener('load', function (e) {
        var widgetInstance = XPay2PlayWidget.create(options);
    }, false);
    var head = document.getElementsByTagName('head')[0];
    head.appendChild(s);
</script>

위의 코드에 추가할 데이터:

YOUR-PROJECT-ID - 게시자 계정에 프로젝트 ID(프로젝트 – 프로젝트 설정 – 일반 설정 – 프로젝트 ID)
YOUR-ITEM-TYPE - 아이템 유형:
- 게임 – digital_content (이전 관리 메소드 프로젝트) 또는 game_key (새로운 관리 메소드 프로젝트)
- 실물 상품 – physical_good
- 가상 아이템 – virtual_item
- 가상 화폐 – virtual_currency
YOUR-ITEM-SKU - 아이템 SKU. 프로젝트가 새로운 스토어 관리 메소드를 사용하고 그 메소드로 게임 키를 판매한다면, YOUR-ITEM-SKU_DRM 형식에서 DRM추가를 합니다.

위젯 구성에 대한 추가 정보는

GitHub

을 참조하세요.

스토어 UI를 통해 판매

스토어 UI를 통해 가상 아이템 및 가상 화폐를 판매하기 위해 별도의 웹 애플리케이션을 구현하거나 스토어 UI를 게임 내부에 구현할 수 있습니다. 아이템 목록을 가져오고 이를 가져와서 작동하도록 하려면

Store API

를 사용하거나 데모 버전을 기반으로 스토어를 직접 제작해야 합니다.

Store API 기준

Store API 메소드를 통합하여 스토어의 프론트 엔트 파트를 만들 수 있습니다:

아이템 목록 가져오기.
아이템 구매:
- 한 개 아이템 빠른 구매. 결제UI를 열기 위한 토큰이 응답으로 전달됩니다.
- 여러 아이템 구매:
  - 장바구니에 아이템 추가.
  - 장바구니의 아이템 목록 가져오기.
  - 장바구니 아이템 비용 지불. 결제 UI를 열기 위한 토큰이 응답으로 전달됩니다.

메소드가 올바르게 작동할 수 있도록 적합한 인증 옵션을 선택하세요.

데모 버전 기준

스토어 데모 버전을 사용하여 API 기능을 확인할 수 있습니다. 해당 코드는

GitHub

에 업로드되어 있습니다. 이러한 코드는 자체 버전을 만드는 기초로 사용할 수도 있습니다.

인증 설정

권한이 있는 사용자와 권한이 없는 사용자 모두 구매할 수 있습니다.

인증되지 않은 사용자

인증 없이 사용자가 게임과 실물 상품을 구입할 수 있습니다.

게임 판매를 위해 기본 통합에서 구매 옵션을 사용하세요.

실물 상품을 판매하려면 Store API 메소드를 호출할 때 x-unauthorized-id 사용자 식별자를 전달해야 합니다. 해당 식별자는 프론트엔드 측에서 숫자 또는 라인으로 생성할 수 있습니다. 식별자 생성 라이브러리의 예입니다.

인증된 사용자

사용자 인증을 위한 옵션은 다음과 같습니다.

엑솔라 로그인을 통합한 경우 요청이 엑솔라 로그인 JWT을 통해 인증됩니다.
자체 인증 시스템을 보유한 경우 요청이 페이 스테이션 액세스 토큰을 통해 인증됩니다.

엑솔라 로그인을 통한 인증 설정

지침에 따라 게시자 계정에서 프로젝트를 설정합니다.
인증 메소드 콜백을 구현합니다. 이때 JSON Web Token 또는 OAuth 2.0 프로토콜을 따르도록 합니다.

사용자 데이터가 엑솔라 스토리지에 저장되어 있는 경우, 다음 메소드를 구현합니다.

등록 (JWT 또는 OAuth2.0)
인증(다음 중 하나를 선택):
- 사용자 이름 및 암호 (JWT 또는 OAuth2.0)
- 소셜 네트워크 (JWT 또는 OAuth2.0)
암호 재설정

사용자 데이터가 PlayFab 데이터베이스에 저장되어 있는 경우,

PlayFab

스토리지 레시피를 사용합니다. 사용자 데이터가 사용자 정의 스토리지에 저장되어 있는 경우, 사용자 정의 스토리지 레시피를 사용합니다.

페이 스테이션 액세스 토큰을 통한 인증 설정

인증 절차:

클라이언트가 서버로 인증 요청을 전송합니다.
귀하의 서버가 엑솔라 서버로 Merchant ID와 API key를 전달하고 access_token을 요청합니다.
엑솔라 서버가 귀하의 서버로 access_token을 전송합니다.
귀하의 서버가 귀하의 클라이언트로 access_token을 전송합니다.

반환된 access_token이 게임 클라이언트가 전송한 요청을 인증하기 위한 인증 토큰으로 사용됩니다.

프로모션 옵션

쿠폰

파트너는 쿠폰 기능을 통해 쿠폰 코드가 포함된 쿠폰 캠페인을 생성할 수 있으며 이러한 쿠폰 코드는 파트너사가 업로드하거나 게시자 계정에서 생성할 수 있습니다. 쿠폰은 사용자에게 가상 화폐, 가상 아이템 또는 구독 플랜의 평가 일을 부여할 수 있습니다. (해당하는 경우) 환불 횟수 및 만료 날짜를 사용자 정의할 수 있습니다.

레시피 보기

레이블

파트너는 레이블 기능을 통해 가상 아이템 및 가상 화폐 패키지 프로모션에 레이블을 부착할 수 있습니다. 예를 들어, "Best Value"를 부착할 수 있습니다.

레시피 보기

보너스

사용자는 보너스 기능을 통해 구매 시 보너스 아이템을 받을 수 있습니다. 보너스는 다음 중 하나가 될 수 있습니다.

가상 화폐
구독 평가일
가상 아이템
게임
실제 상품(예: 머천다이즈)

레시피 보기

레시피

당사 레시피를 통해 Buy Button의 고급 기능 일부를 체험해볼 수 있습니다.

Buy Button

작동 방식

사용자 플로우

통합 절차

프로젝트 생성

현금화 옵션

가상 머니

설정

웹훅 설정

레시피

가상 아이템

설정

웹훅 설정

레시피

게임 키

기본 통합

고급 통합

웹훅 설정

레시피

아이템 판매

직접 링크를 통해 판매

게임 액세스 판매

가상 아이템 및 가상 화폐 판매

위젯을 통해 판매

스토어 UI를 통해 판매

Store API 기준

데모 버전 기준

인증 설정

인증되지 않은 사용자

인증된 사용자

엑솔라 로그인을 통한 인증 설정

페이 스테이션 액세스 토큰을 통한 인증 설정

프로모션 옵션

쿠폰

레이블

보너스

레시피

튜토리얼