아키텍처
PlayCamp SDK API는 게임 서버를 통해 연동됩니다.
역할 분담
| 구성 요소 | 역할 |
|---|
| 게임 클라이언트 | 유저 인터페이스 (크리에이터 선택 UI, 쿠폰 입력 화면 등) |
| 게임 서버 | API 호출, 비즈니스 로직 처리, Server Key 보관 |
| PlayCamp SDK API | 데이터 저장, 정산 계산, 통계 집계, 웹훅 발송 |
데이터 흐름 예시
크리에이터 선택
유저가 게임에서 크리에이터를 선택
후원 등록
게임 서버가 POST /v1/server/sponsors 호출
결제 등록
게임 서버가 POST /v1/server/payments 호출
자동 귀속
SDK API가 해당 결제를 크리에이터에게 자동 귀속
시작하기
필수 연동 API
캠페인 진행을 위해 반드시 연동해야 하는 Server API 3개입니다.
| 기능 | API | 설명 |
|---|
| 후원 등록 | POST /sponsors | 유저가 크리에이터를 후원. 결제 귀속의 핵심 |
| 쿠폰 검증 | POST /coupons/validate | 쿠폰 코드 유효성 검사 |
| 결제 등록 | POST /payments | 인게임 결제 등록. 정산의 기초 데이터 |
캠페인 게시를 위해 연동 검증이 필요합니다. 위 3개 API를 각각 최소 1번 이상 Live 환경에서 호출해야 캠페인을 게시할 수 있습니다. 이 검증이 완료되지 않으면 캠페인 승인 화면에 다음 메시지가 표시됩니다:“게임과 PlayCamp가 연동되어 있지 않습니다. API를 통해 연동이 필요합니다.”검증 호출 시 isTest: true를 사용할 수 있습니다. 테스트 모드 요청도 연동 검증으로 인정되며, 실제 데이터는 저장되지 않습니다.
API 연동
게임 서버에 필수 API 3개를 구현합니다
Live 환경에서 호출
각 API를 Live 환경(https://sdk-api.playcamp.io)에서 최소 1번씩 호출합니다. isTest: true 사용이 가능합니다.
캠페인 승인 요청
3개 API 검증이 완료되면 PlayCamp 관리자에게 승인을 요청합니다
캠페인 게시
승인 후 연동 경고 메시지가 사라지고 캠페인이 최종 게시 상태로 전환됩니다
캠페인/크리에이터 조회, 웹훅 등은 선택적으로 연동하면 됩니다.
API 키 발급
PlayCamp 플랫폼에서 프로젝트 생성 후 API 키를 발급받습니다.
| 키 타입 | 용도 | 보관 위치 |
|---|
| Server Key | 모든 API 호출 (읽기/쓰기) | 게임 서버 (안전하게 보관) |
| Client Key | 조회 API만 (읽기 전용) | 게임 클라이언트 (선택적 사용) |
Server Key는 절대 클라이언트에 노출하지 마세요.
인증 방식
모든 API 요청에 Bearer Token 인증을 사용합니다.
Authorization: Bearer {keyId}:{secret}
Authorization: Bearer ak_server_abc123def456:xyz789secretkey
서버 환경
| 환경 | URL | 용도 |
|---|
| Sandbox | https://sandbox-sdk-api.playcamp.io | 개발/테스트 |
| Live | https://sdk-api.playcamp.io | 실제 서비스 |
개발 중에는 Sandbox 환경을 사용하세요. Sandbox는 Live와 완전히 격리되어 있습니다.
연동 순서
1. POST /sponsors → 유저가 크리에이터 선택 (후원)
2. POST /coupons/validate → 쿠폰 코드 검증
3. POST /payments → 인게임 결제 발생 시 등록
SDK
타입 안전한 연동을 위해 HTTP 직접 호출 대신 공식 SDK를 사용할 수 있습니다:
npm install @playcamp/node-sdk
import { PlayCampServer } from '@playcamp/node-sdk';
const server = new PlayCampServer('your_server_key:your_secret', {
environment: 'sandbox',
});
go get github.com/playcamp/playcamp-go-sdk
import playcamp "github.com/playcamp/playcamp-go-sdk"
server, err := playcamp.NewServer("your_server_key:your_secret",
playcamp.WithEnvironment(playcamp.EnvironmentSandbox),
)
테스트 모드
캠페인 시작 전 isTest: true 파라미터를 사용하여 API 연동을 테스트할 수 있습니다.
curl -X POST "https://sandbox-sdk-api.playcamp.io/v1/server/payments" \
-H "Authorization: Bearer ak_server_xxx:secret" \
-H "Content-Type: application/json" \
-d '{
"userId": "test_user",
"transactionId": "test_txn_001",
"productId": "gem_pack_100",
"amount": 9900,
"currency": "KRW",
"platform": "Android",
"distributionType": "MOBILE_STORE",
"purchasedAt": "2024-01-15T10:30:00.000Z",
"isTest": true
}'
const server = new PlayCampServer('your_server_key:your_secret', {
environment: 'sandbox',
isTest: true,
});
const payment = await server.payments.create({
userId: 'test_user',
transactionId: 'test_txn_001',
productId: 'gem_pack_100',
amount: 9900,
currency: 'KRW',
platform: 'Android',
distributionType: 'MOBILE_STORE',
purchasedAt: new Date('2024-01-15T10:30:00Z'),
});
server, err := playcamp.NewServer("your_server_key:your_secret",
playcamp.WithEnvironment(playcamp.EnvironmentSandbox),
playcamp.WithTestMode(true),
)
purchasedAt, _ := time.Parse(time.RFC3339, "2024-01-15T10:30:00Z")
payment, err := server.Payments.Create(ctx, playcamp.CreatePaymentParams{
UserID: "test_user",
TransactionID: "test_txn_001",
ProductID: "gem_pack_100",
Amount: 9900,
Currency: "KRW",
Platform: playcamp.PaymentPlatformAndroid,
DistributionType: playcamp.String("MOBILE_STORE"),
PurchasedAt: purchasedAt,
})
- 요청 파라미터 검증은 실제와 동일하게 수행
- 데이터는 DB에 저장되지 않음
- Mock 응답 반환
권장: 캠페인 시작 전 연동 시에는 isTest: true를 사용하여 테스트하세요. isTest는 Sandbox와 Live 환경 모두에서 사용 가능합니다. 실제 캠페인 운영 시에는 isTest 파라미터를 제거하세요.