WebView 연동

PlayCamp가 제공하는 웹 기반 UI를 통해 부스트/쿠폰 기능을 제공하는 방법을 설명합니다.

개요

WebView는 PlayCamp가 제공하는 부스트/쿠폰 관리 웹 UI입니다. 게임 내 임베디드 브라우저(WebView)뿐만 아니라 외부 브라우저에서도 동작합니다. 별도의 UI 개발 없이 크리에이터 부스트와 쿠폰 기능을 제공할 수 있습니다.

게임 내 임베디드 브라우저, 외부 브라우저(모바일/PC) 모두 지원됩니다. 게임 환경에 맞게 적합한 방식을 선택하세요.

Server API 직접 연동 vs WebView 비교

항목	Server API 직접 연동	WebView
UI 개발	게임사가 직접 구현 필요	PlayCamp 제공 (추가 개발 불필요)
연동 난이도	각 API별 개별 연동	OTT 발급 1개 API만 연동
커스터마이징	완전한 자유도	테마 색상/폰트 커스터마이징
다국어	게임사가 직접 처리	자동 지원 (한국어/영어)
적합한 경우	게임 UX에 완벽히 맞춰야 할 때	빠르게 기능을 제공하고 싶을 때

WebView와 Server API 직접 연동은 동시에 사용 가능합니다. 예를 들어 부스트는 WebView로, 결제 등록은 Server API로 처리할 수 있습니다.

아키텍처

연동 흐름

OTT 발급 (게임 서버)

게임 서버에서 Server API Key로 OTT(One-Time Token)를 발급합니다.

WebView 열기 (게임 클라이언트)

게임 서버로부터 받은 OTT를 URL 파라미터에 포함하여 WebView를 엽니다.

https://sandbox-sdk-api.playcamp.io/webview/?ott={token}

유저 인터랙션

유저가 WebView에서 크리에이터 부스트 등록/변경/해제, 쿠폰 검증/사용 등을 수행합니다. 별도의 게임 서버 처리가 필요 없습니다.

웹훅으로 결과 수신

WebView에서 발생한 이벤트(부스트 등록, 쿠폰 사용 등)가 웹훅으로 게임 서버에 전달됩니다.

OTT 발급 API

요청

cURL
Node SDK
Go SDK

curl -X POST "https://sandbox-sdk-api.playcamp.io/v1/server/webview/ott" \
  -H "Authorization: Bearer ak_server_xxx:secret" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_12345"
  }'

const result = await server.webview.createOtt({
  userId: 'user_12345',
  campaignId: 'campaign_123',       // optional
  codeChallenge: 'challenge_value', // optional
  callbackId: 'cb_001',             // optional
  metadata: { key: 'value' },       // optional
});

console.log(result.ott);       // 일회용 토큰
console.log(result.expiresAt); // 만료 시각 (ISO 8601)

result, err := server.Webview.CreateOTT(ctx, playcamp.WebviewOttParams{
    UserID:        "user_12345",
    CampaignID:    "campaign_123",       // optional
    CodeChallenge: "challenge_value",    // optional
    CallbackID:    "cb_001",             // optional
    Metadata:      map[string]any{"key": "value"}, // optional
})

fmt.Println(result.OTT)       // 일회용 토큰
fmt.Println(result.ExpiresAt) // 만료 시각

파라미터

필드	타입	필수	설명
`userId`	string	O	게임 내 유저 식별자
`campaignId`	string	-	특정 캠페인으로 WebView 범위 제한
`codeChallenge`	string	-	PKCE S256 challenge (Base64URL-encoded SHA256, 43-128자)
`callbackId`	string	-	웹훅 추적용 ID
`metadata`	object	-	추가 메타데이터 (세션에 저장)

응답 (201 Created)

{
  "data": {
    "ott": "a1b2c3d4e5f6...64자hex",
    "expiresIn": 60
  }
}

필드	설명
`ott`	One-Time Token (64자 hex 문자열)
`expiresIn`	만료까지 남은 시간 (초, 기본 60초)

OTT는 1회성이며 60초 TTL입니다. 발급 후 빠르게 WebView를 열어야 합니다. 반드시 게임 서버에서 발급해야 하며, 클라이언트에서 직접 발급하면 Server Key가 노출됩니다.

WebView URL 구성

기본 URL

환경	URL
Sandbox	`https://sandbox-sdk-api.playcamp.io/webview/?ott={token}`
Live	`https://sdk-api.playcamp.io/webview/?ott={token}`

옵션 파라미터

파라미터	설명	예시
`lang`	언어 설정 (ko, en)	`?ott=xxx&lang=en`
`tabs`	표시할 탭 제한 (쉼표 구분)	`?ott=xxx&tabs=sponsor,coupon`

tabs 옵션

값	설명
`sponsor`	부스트 관리 탭
`coupon`	쿠폰 사용 탭
`campaigns`	캠페인 목록 탭
`creators`	크리에이터 검색 탭

tabs 미지정 시 기본 탭이 표시됩니다 (sponsor, coupon).

테마 커스터마이징

WebView의 색상과 폰트를 URL 파라미터로 커스터마이징할 수 있습니다.

파라미터	설명	기본값	예시
`primaryColor`	버튼/강조 색상 (hex)	게임 테마 색상	`primaryColor=FF6B35`
`bgColor`	배경 색상 (hex)	다크 테마	`bgColor=1a1a2e`
`textColor`	텍스트 색상 (hex)	밝은 텍스트	`textColor=ffffff`
`fontFamily`	폰트 패밀리	시스템 기본	`fontFamily=Noto Sans KR`

hex 색상값은 # 없이 입력합니다. 예: primaryColor=FF6B35

전체 예시

/webview/?ott=xxx&lang=ko&tabs=sponsor,coupon&primaryColor=FF6B35&bgColor=1a1a2e&textColor=ffffff

주요 기능

부스트 관리

WebView에서 유저가 크리에이터를 검색하고 부스트를 등록/변경/해제할 수 있습니다.

크리에이터 검색: 크리에이터 키 또는 이름으로 검색 (실시간 자동완성)
부스트 등록: 선택한 크리에이터에게 부스트 등록
부스트 변경: 다른 크리에이터로 변경 (30일 쿨다운 적용)
부스트 해제: 현재 부스트 해제

크리에이터 키 프리필 URL에 크리에이터 키를 포함하여 검색 폼을 미리 채울 수 있습니다:

/webview/?ott=xxx#sponsor?creatorKey=ABC12

쿠폰 사용

2단계로 쿠폰을 사용합니다: 검증 → 사용

코드 입력: 5-50자, 자동 대문자 변환, 한글 입력 시 영문 키 위치로 자동 변환
검증: 유효성 확인 및 보상 아이템 미리보기
사용: 확인 버튼으로 최종 사용 (사용 ID 반환)

웹훅 이벤트 연동

WebView에서 유저가 수행한 액션은 웹훅으로 게임 서버에 전달됩니다.

WebView에서 발생하는 이벤트

이벤트	설명	주요 data 필드
`sponsor.created`	부스트 등록	`userId`, `campaignId`, `creatorKey`
`sponsor.ended`	부스트 해제	`userId`, `campaignId`, `creatorKey`
`coupon.redeemed`	쿠폰 사용	`couponCode`, `userId`, `usageId`, `reward`

웹훅 페이로드 예시

sponsor.created (부스트 등록)

{
  "events": [
    {
      "event": "sponsor.created",
      "timestamp": "2024-01-15T10:30:00.000Z",
      "callbackId": "cb_001",
      "data": {
        "userId": "user_12345",
        "campaignId": "campaign_001",
        "creatorKey": "ABC12"
      }
    }
  ]
}

coupon.redeemed (쿠폰 사용)

{
  "events": [
    {
      "event": "coupon.redeemed",
      "timestamp": "2024-01-15T10:31:00.000Z",
      "callbackId": "cb_001",
      "data": {
        "couponCode": "CREATOR-ABC12-001",
        "userId": "user_12345",
        "usageId": 5678,
        "reward": [{ "itemId": "gem", "itemQuantity": 100 }]
      }
    }
  ]
}

OTT 발급 시 callbackId를 지정하면, 해당 세션에서 발생하는 모든 웹훅 이벤트에 지정된 ID가 포함됩니다. 웹훅 수신 및 서명 검증 방법은 웹훅 이벤트 페이지를 참고하세요.

보안

OTT (One-Time Token)

1회성: OTT는 세션 교환 시 즉시 삭제됩니다. 재사용 불가합니다
60초 TTL: 발급 후 60초 내에 사용해야 합니다
서버 발급 필수: Server API Key가 필요하므로 게임 서버에서만 발급 가능

세션 관리

세션 쿠키: httpOnly, SameSite=strict 설정으로 XSS/CSRF 공격 방지
세션 TTL: 10분 (마지막 API 호출 기준으로 자동 연장)
단일 세션: 같은 유저는 하나의 세션만 허용. 새 세션 생성 시 기존 세션 자동 무효화

CSRF 보호

WebView 내부의 상태 변경 요청(POST/PUT/DELETE)에는 CSRF 토큰이 자동으로 포함됩니다. 게임사에서 별도로 처리할 필요 없습니다.

PKCE (선택)

앱 환경에서 추가 보안이 필요한 경우 PKCE(Proof Key for Code Exchange)를 사용할 수 있습니다.

import crypto from 'crypto';

// 1. 코드 생성 (게임 서버)
const codeVerifier = crypto.randomBytes(32).toString('base64url');
const codeChallenge = crypto
  .createHash('sha256')
  .update(codeVerifier)
  .digest('base64url');

// 2. OTT 발급 시 codeChallenge 포함
const { ott } = await server.webview.createOtt({
  userId: 'user_12345',
  codeChallenge,
});

// 3. WebView URL에 codeVerifier 포함
const url = `https://sandbox-sdk-api.playcamp.io/webview/?ott=${ott}&code_verifier=${codeVerifier}`;

FAQ

세션 만료 시 어떻게 되나요?

세션이 만료되면 WebView에 재접속 안내 화면이 표시됩니다. 유저가 계속 사용하려면 게임 서버에서 새 OTT를 발급받아 WebView를 다시 열어야 합니다.

세션 TTL은 10분이며, API 호출 시마다 자동 연장됩니다. 단, 유휴 상태(아무 동작 없이 방치)에서는 연장되지 않습니다.

campaignId 스코핑이란?

OTT 발급 시 campaignId를 지정하면 WebView 전체가 해당 캠페인으로 범위가 제한됩니다:

부스트 등록/변경/해제 시 해당 캠페인의 크리에이터만 표시
캠페인 목록 대신 해당 캠페인 정보만 표시
해당 캠페인에 참여하는 크리에이터만 검색 가능

존재하지 않는 campaignId를 지정하면 OTT 발급이 실패합니다 (404).

다국어는 어떻게 지원되나요?

기본: 브라우저 언어 설정에 따라 자동 감지 (한국어/영어)
URL 파라미터 지정: ?lang=ko 또는 ?lang=en
유저가 변경한 언어 설정은 브라우저에 저장되어 다음 접속 시에도 유지됩니다

OTT를 미리 발급해둘 수 있나요?

권장하지 않습니다. OTT는 60초 TTL이므로, 유저가 WebView 열기를 요청하는 시점에 발급하세요.

WebView에서 결제도 되나요?

아니요. WebView는 부스트와 쿠폰 기능만 제공합니다. 결제 등록은 게임 서버에서 Server API를 직접 호출해야 합니다.

동시에 여러 기기에서 접속하면 어떻게 되나요?

같은 유저는 하나의 세션만 허용됩니다. 새 기기에서 WebView를 열면 이전 기기의 세션이 자동으로 무효화되고, 이전 기기에서는 세션 만료 안내가 표시됩니다.

플랫폼

개발사 가이드

크리에이터 가이드

개요

Server API 직접 연동 vs WebView 비교

아키텍처

연동 흐름

OTT 발급 API

요청

파라미터

응답 (201 Created)

WebView URL 구성

기본 URL

옵션 파라미터

테마 커스터마이징

주요 기능

부스트 관리

쿠폰 사용

웹훅 이벤트 연동

WebView에서 발생하는 이벤트

웹훅 페이로드 예시

보안

OTT (One-Time Token)

세션 관리

CSRF 보호

PKCE (선택)

FAQ

세션 만료 시 어떻게 되나요?

campaignId 스코핑이란?

다국어는 어떻게 지원되나요?

OTT를 미리 발급해둘 수 있나요?

WebView에서 결제도 되나요?

동시에 여러 기기에서 접속하면 어떻게 되나요?

​개요

​Server API 직접 연동 vs WebView 비교

​아키텍처

​연동 흐름

​OTT 발급 API

​요청

​파라미터

​응답 (201 Created)

​WebView URL 구성

​기본 URL

​옵션 파라미터

​테마 커스터마이징

​주요 기능

​부스트 관리

​쿠폰 사용

​웹훅 이벤트 연동

​WebView에서 발생하는 이벤트

​웹훅 페이로드 예시

​보안

​OTT (One-Time Token)

​세션 관리

​CSRF 보호

​PKCE (선택)

​FAQ

​세션 만료 시 어떻게 되나요?

​campaignId 스코핑이란?

​다국어는 어떻게 지원되나요?

​OTT를 미리 발급해둘 수 있나요?

​WebView에서 결제도 되나요?

​동시에 여러 기기에서 접속하면 어떻게 되나요?

개요

Server API 직접 연동 vs WebView 비교

아키텍처

연동 흐름

OTT 발급 API

요청

파라미터

응답 (201 Created)

WebView URL 구성

기본 URL

옵션 파라미터

테마 커스터마이징

주요 기능

부스트 관리

쿠폰 사용

웹훅 이벤트 연동

WebView에서 발생하는 이벤트

웹훅 페이로드 예시

보안

OTT (One-Time Token)

세션 관리

CSRF 보호

PKCE (선택)

FAQ

세션 만료 시 어떻게 되나요?

campaignId 스코핑이란?

다국어는 어떻게 지원되나요?

OTT를 미리 발급해둘 수 있나요?

WebView에서 결제도 되나요?

동시에 여러 기기에서 접속하면 어떻게 되나요?