아이템 시스템 및 플랫폼 유료 스토어
이 시스템은 게임 플랫폼을 위한 통합 유료 아이템 관리 솔루션을 제공하며, 스탠드얼론 게임의 아이템 구매, 배포, 통계 등의 기능을 지원하고 아이템 구매, 조회, 증감 및 프로세스 트리거 배포 기능을 구현합니다.
- 핵심 기능: 아이템 구매, 소유 조회, 증감 작업, 변경 모니터링, 게임 프로세스 트리거 배포
1. 개발자 백엔드 관리 기능
- 개발자는 백엔드를 통해 수동으로 아이템 데이터를 생성할 수 있으며, 테이블(아이템 유닛 테이블)과 아이템 아이콘 업로드를 지원합니다.
- 유료 스토어 아이템은 현재 수동 생성만 지원합니다.
- 최대 5000개의 아이템 데이터 항목 생성을 지원합니다.
- 현재는 일회성 구매 및 인앱 구매 유형의 게임만 지원합니다.
- 아이템 생성 후 승인이 필요하며, 승인되면 기본적으로 활성화 상태가 됩니다.
아이템 관리 기능:
아이템 ID: 고유 식별자, 생성 후 수정 불가
아이템 이름 및 아이콘: 프론트엔드 표시에 사용
아이템 아이콘: 아이콘 이미지 수동 교체 지원
아이템 생성 규칙: 게임 아이템과 스토어 유료 아이템 선택 지원
아이템 제한: 플랫폼을 통한 플레이어 배포 제한 설정 지원, 일일 배포 수량 제한, 총 수량 제한 또는 제한 없음
아이템 재고: 수량 입력 또는 제한 없음 선택 가능
아이템 가치 설정:
무료 아이템(Platform activities): 플랫폼 활동을 통한 배포 지원.
유료 구매(Paid purchase): 아이템 스토어 유료 구매 지원.
기본 미국 달러 기준 가격 책정
아이템 단위 가격은 0.0001 USD까지 정밀도 지원
스토어 유료 아이템 최소 가치 입력은 1 USD
2. 아이템 SDK 통합
핵심 인터페이스 설명
| 인터페이스 이름 | 메서드 서명 | 기능 설명 |
|---|---|---|
| 구매 창 열기 | openBuyGameItemsDialog(level: number) | 게임 내 기능 UI를 통해 스토어 아이템 구매 대화 상자를 엽니다. |
| 소유 아이템 가져오기 | getUserGameItems(): GameItem[] | 게임 입장 시 플레이어의 현재 아이템 목록을 조회합니다 (ID 및 수량 포함). |
| 아이템 추가 | addGameItem(itemId: string, amount: number) | 게임 진행 중 아이템을 배포합니다 (구매, 레벨 보상, 미션 완료 등 시나리오 지원). |
| 아이템 감소 | subtractGameItem(itemId: string, amount: number) | 아이템을 소비합니다 (게임 진행 중 사용 또는 소비 시나리오, 공제 후 수량은 음수가 아님). |
| 변경 알림 구독 | subscribeGameItemChange(callback: (res: GameItemChange) => void) | 스토어 유료 아이템 결제 완료 시 실행되는 콜백 메서드. |
주요 데이터 형식
- **GameItem (아이템 정보)**:
{ itemId: string, amount: number } - **GameItemChange (변경 정보)**:
{ itemId: string, amount: number, changeType: 'add'|'subtract', total: number }
2.1 소유 아이템 목록 가져오기
javascript
// 플레이어의 소유 아이템 목록 가져오기 (게임 초기화 시 호출)
const items = window.JOGOS_SDK.gameItem.getUserGameItems();
console.log('소유 아이템:', items);2.2 아이템 구매 창 열기
javascript
// 아이템 구매 창 열기
window.JOGOS_SDK.gameItem.openBuyGameItemsDialog(10);2.3 아이템 추가
javascript
// 아이템 추가 (ID: 3232addasdda3aa2, 수량: 10)
window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 10);2.4 아이템 감소
javascript
// 아이템 감소 (ID: 3232addasdda3aa2, 수량: 5)
window.JOGOS_SDK.gameItem.subtractGameItem('3232addasdda3aa2', 5);2.5 아이템 변경 알림 구독
javascript
// 아이템 변경 알림 구독
window.JOGOS_SDK.gameItem.subscribeGameItemChange((res) => {
console.log('아이템 변경:', res);
});2.6 유료 아이템 구매 전체 흐름
javascript
// 1. 유료 아이템 구매 시작 (상품 ID: item_gold_100, 100 골드 코인 아이템에 해당)
async function buyGoldItem() {
try {
const orderNo = await window.JOGOS_SDK.payment.buyGoods('item_gold_100');
console.log('주문 생성 성공, 주문 번호:', orderNo);
} catch (err) {
console.error('주문 생성 실패:', err);
alert('구매 시작 실패, 나중에 다시 시도해 주세요');
}
}
// 2. 결제 성공 알림 구독 (게임 초기화 시 호출)
window.JOGOS_SDK.payment.subscribeOrderPaid(async (order) => {
console.log('결제 성공, 주문 상세:', order);
if (order.status === 'success') {
// 3. 해당 아이템 배포 (상품 ID: item_gold_100은 아이템 ID: 3232addasdda3aa2에 해당)
window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 100);
// 4. 플랫폼에 배송 알림 (반드시 호출해야 함,否则 주문 상태 이상)
await window.JOGOS_SDK.payment.deliverGoods(order.orderNo);
alert('100 골드 코인 구매 성공, 가방에 배포되었습니다!');
}
});
// 3. 예외 시나리오: 주문 상세 조회 (예: 결제 후 아이템 미수령)
async function checkOrder(orderNo) {
try {
const order = await window.JOGOS_SDK.payment.getOrderDetail(orderNo);
console.log('주문 상세 조회:', order);
if (order.status === 'success') {
// 아이템 재배포
window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 100);
await window.JOGOS_SDK.payment.deliverGoods(orderNo);
}
} catch (err) {
console.error('주문 조회 실패:', err);
}
}2.7 게임 프로세스 트리거 아이템 배포 (예시: 레벨 클리어 보상)
javascript
// 레벨 10 클리어 시 아이템 배포 트리거 (중복 수령 방지를 위한 중복 제거 로직 포함)
function onLevel10Clear() {
// 스탠드얼론 게임: 로컬 스토리지를 사용하여 배포 상태 기록
const hasIssued = localStorage.getItem('level10_award_issued');
if (hasIssued) {
alert('이 레벨 보상은 이미 수령하였습니다, 중복 수령할 수 없습니다');
return;
}
// 아이템 배포 (ID: 3232addasdda3aa2, 수량: 10)
window.JOGOS_SDK.gameItem.addGameItem('3232addasdda3aa2', 10);
// 배포 상태 기록
localStorage.setItem('level10_award_issued', 'true');
alert('레벨 10 클리어 성공! 10개의 아이템 보상을 획득했습니다');
}