Store API 통합

작동 방식

Store API를 연결하여 여러분 스토어의 서버 부분을 구현하거나 이미 엑솔라로 서버 통합(토큰으로 통합)을 구현한 경우에는 새 Store API 메소드로 전환할 수 있습니다.

주요 기능:

  • 엑솔라 로그인이나 페이 스테이션 액세스 토큰을 통한 인증
  • 가상 아이템 관리
  • 사용자 인벤토리 관리
  • 카트 및 주문 관리

사용자

  • 스토어 인터페이스를 구현하고 서버 구현을 위해 서드파티 솔루션을 사용하려고 하는 파트너.
  • 이미 엑솔라와의 서버 통합을 구현하고 스토어를 새 Store API 메소드로 연결하려고 하는 경우.

획득 방법

앱에 Store API 연결 방법:

  1. 설정게시자 계정에서 가상 아이템.
  2. 인증 설정.
  3. 구현 스토어 관리 메소드.

통합하려면 프로젝트 설정 > 웹훅에 표시된 프로젝트 ID가 필요합니다. 프로젝트 ID는 Store API 요청에 사용됩니다.

게시자 계정의 가상 아이템 모듈 설정

  1. 프로젝트로 이동하여 프로젝트 생성 버튼을 클릭합니다.
  2. 프로젝트 이름을 추가하고 생성을 클릭.

  1. 다음 프로젝트 설정 > 통합 설정으로 이동하여 새 스토어 관리 메소드 통합 토글러 활성화 여부를 확인합니다.
  2. 다음 스토어를 여러분 프로젝트에 연결합니다.
  3. 다음 가상 아이템 모듈을 연결합니다.

  1. 아이템 그룹을 생성합니다.

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

  1. 아이템 생성 후 스토어에서 그룹 표시 기능을 켭니다.

인증 설정

다음 사용자 인증 옵션을 사용할 수 있습니다:

엑솔라 로그인을 통한 인증

  1. 게시자 계정 프로젝트를 지침에 따라 설정합니다.
  2. JSON 웹 토큰 혹은 OAuth 2.0 프로토콜을 통하여 인증 메소드 호출을 구현합니다.

사용자 데이터가 엑솔라 데이터 스토리지에 보관되는 경우, 다음 메소드 호출을 구현합니다:

사용자 데이터가 PlayFab 데이터 스토리지에 보관되는 경우, PlayFab 레시피 사용.

사용자 데이터를 여러분 자신이 보관하는 경우, 사용자 정의 스토리지 레시피.

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

인증 절차:

  1. 앱(클라이언트)에서 서버에 인증 요청을 보냅니다.
  2. 여러분의 서버에서 엑솔라 서버로 판매자 ID 및 API 키를 보내고 access_token를 요청합니다.
  3. 엑솔라 서버는 access_token를 여러분의 서버 보냅니다.
  4. 여러분의 서버는 access_token를 여러분 클라이언트에게 송부합니다.

반환된 access_token는 Store API 인증 및 스토어 인터페이스 구축에 인증 토큰으로 사용됩니다.

스토어 관리 방식

스토어 관리 방식에는 다음과 같은 방식 그룹이 포함되어 있습니다.

Get Virtual Items List

스토어에 추가된 전체 게임 아이템 목록을 표시하려면 Get virtual items list API 방식을 구현합니다.

예제

Copy
Full screen
Small screen
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/items/virtual_items?locale=en");

xhr.send(data);

//RESPONSE

"items": [
    {
      "attributes": [],
      "description": "Conquer your foes with vindication using the Basic Blaster! ",
      "groups": [
        "all",
        "featured",
        "Xsolla",
        "weapons"
      ],
      "image_url": "https://cdn.xsolla.net/img/misc/images/0c59a7698d4f66c1008b27ee752089b7.png",
      "is_free": false,
      "name": "Xsolla Basic Blaster 1",
      "order": 1,
      "price": {
        "amount": "0.9950000000000000",
        "amount_without_discount": "1.9900000000000000",
        "currency": "USD"
      },
      "sku": "gun_1",
      "type": "virtual_good"

Get Item Groups List

  1. Get item groups list API 메소드를 구현하여 여러분의 스토어에 추가된 가상 아이템 그룹의 전체 목록을 표시합니다.
  2. 다음의 개별 sku 매개 변수 값은 Get virtual items list 메소드에서 반횐되는데 이에 대하여 해당 값이 속하는 그룹의 external_id를 지정합니다. skuexternal_id를 게시자 계정에서 아이템이 그룹 지어진 방식과 같이 일치시킵니다.

예제

Copy
Full screen
Small screen
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/items/groups");

xhr.send(data);

//RESPONSE

  "groups": [
    {
      "children": [],
      "description": "all",
      "external_id": "all",
      "id": 10,
      "image_url": "http://none",
      "level": 0,
      "name": "all",
      "order": null,
      "parent_external_id": null
    }

Get Cart

게임 아이템 구매를 위해 Get cart by ID 또는 Get current user’s cart API 방식을 구현합니다. Cart ID는 아이템 추가/제거에 사용됩니다.

예제

Copy
Full screen
Small screen
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/cart/custom_id?locale=en&currency=USD");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");

xhr.send(data);

//RESPONSE

{
  "cart_id": "custom_id",
  "is_free": true,
  "items": [],
  "price": null
}

Note: 카트 생성 없이 빠르게 아이템 구매를 사용하려면 Create order with specified item API 방식을 사용합니다.

Create Order with All Items

  1. 다음 API 메소드 중 하나를 구현합니다:
    1. Create order with all items from particular cart.
    2. Create order with all items from current cart 현재 카트의 경우에는.

생성한 주문은 New 주문 상태를 받게 됩니다.

  1. 새 창에서 결제 UI를 열려면, 다음 링크를 사용합니다: https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN, 여기서 ACCESS_TOKEN는 주문 생성 시 받은 토큰입니다.
  2. 결제 프로세스 테스트 방법:
    1. 다음 URL 사용: https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN.
    2. 요청에서 sandbox 매개 변수를 true으로 설정합니다.
    3. 테스트용 은행 카드 목록을 사용합니다.

예제

Copy
Full screen
Small screen
var data = JSON.stringify({
  "currency": "USD",
  "locale": "en",
  "sandbox": false
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://store.xsolla.com/api/v2/project/44056/payment/cart/custom_id");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");

xhr.send(data);

//RESPONSE  

{
  "order_id": 641,
  "token": "f4puMEFFDZcx9nv5HoNHIkPe9qghvBQo"
}

Get Order

Get order API 메소드를 구현하여 구매가 이미 처리되었는지 확인합니다. 다음 주문 상태가 가능합니다:

  • New — 주문이 생성되었으나 지불되지 않음
  • Paid — 주문이 지불됨
  • Cancelled — 주문이 취소됨
  • Done — 주문이 지불되고 아이템이 인벤토리에 추가됨

Note: 주문에 새로운 상태가 부여되기 전에 일회성 확인 절차를 수행할 수있기에 상태 확인은 특정 빈도로 수행됩니다.

예제

Copy
Full screen
Small screen
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/order/656");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");

xhr.send(data);

//RESPONSE

{
  "content": {
    "is_free": false,
    "items": [
      {
        "is_free": false,
        "price": {
          "amount": "0.9950",
          "amount_without_discount": "1.9900",
          "currency": "USD"
        },
        "quantity": 123,
        "sku": "gun_1"
      }
    ],
    "price": {
      "amount": "122.3850",
      "amount_without_discount": "122.3850",
      "currency": "USD"
    }
  },
  "order_id": 656,
  "status": "new"
}

Get User’s Inventory

구매 후 인벤토리에 추가된 아이템 목록을 가져오려면 Get user’s inventory API 가져오기 방식을 구현합니다.

예제

Copy
Full screen
Small screen
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/user/inventory/items");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");

xhr.send(data);

//RESPONSE

{
  "items": [
    {
      "description": "Conquer your foes with vindication using the Basic Blaster! ",
      "image_url": "https://cdn.xsolla.net/img/misc/images/0c59a7698d4f66c1008b27ee752089b7.png",
      "instance_id": null,
      "long_description": "Conquer your foes with vindication using the Basic Blaster! Conquer your foes with vindication using the Basic Blaster! ",
      "name": "Xsolla Basic Blaster 1",
      "quantity": 22,
      "sku": "gun_1",
      "type": "virtual_good"
    },
    {
      "description": "Protect your noggin' with style",
      "image_url": "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png",
      "instance_id": null,
      "long_description": "merchant_virtual_items_virtual_item_long_description_159429",
      "name": "Xsolla Helmet",
      "quantity": 18,
      "sku": "helmet_1",
      "type": "virtual_good"
    }
  ]
}