> ## Documentation Index > Fetch the complete documentation index at: https://playcamp.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # 플레이타임 세션 기록 > 단일 플레이타임 세션을 기록합니다. **자동 귀속:** - `campaignId` 미지정 시 프로젝트의 활성 캠페인 스폰서로 자동 귀속 **멱등성:** - 고유 키는 `projectId` + `sessionId` 입니다 - 중복 `sessionId`는 에러가 아닙니다: 기존 row가 유지되며 응답의 `recorded` 값이 `false`로 반환됩니다 ## OpenAPI ````yaml /api_docs/openapi-ko.yaml post /v1/server/playtime/sessions openapi: 3.0.3 info: title: PlayCamp SDK API description: | PlayCamp SDK API - 게임 분석 및 크리에이터 캠페인 연동 API ## 필수 연동 API (Server API) 캠페인 진행을 위해 반드시 연동해야 하는 API 3개: - `POST /v1/server/sponsors` - 유저가 크리에이터를 부스트 - `POST /v1/server/coupons/validate` - 쿠폰 코드 유효성 검사 - `POST /v1/server/payments` - 인게임 결제 등록 ## 인증 방식 - **Client API**: `Authorization: Bearer {CLIENT_KEY_ID}:{CLIENT_SECRET}` - **Server API**: `Authorization: Bearer {SERVER_KEY_ID}:{SERVER_SECRET}` ## 서버 - **Live**: https://sdk-api.playcamp.io (실제 데이터) - **Sandbox**: https://sandbox-sdk-api.playcamp.io (테스트 데이터) ## 키 타입 - **Client 키**: 게임 클라이언트용 (읽기 전용 - 캠페인, 크리에이터 조회) - **Server 키**: 게임 서버용 (읽기/쓰기 - 쿠폰 사용, 결제 등록 등) ## 테스트 모드 (isTest) 캠페인 실행 전에 `isTest: true` 파라미터를 사용하여 API 연동을 테스트할 수 있습니다. - 요청 파라미터 검증은 실제와 동일하게 수행 - 모의 데이터를 반환하며 실제 DB에 기록되지 않음 - 캠페인 시작 전 Sandbox 환경에서 연동 검증 후, 실제 캠페인 시 `isTest` 파라미터 제거 version: 1.1.0 contact: name: PlayCamp Support servers: - url: https://sdk-api.playcamp.io description: Live Server - url: https://sandbox-sdk-api.playcamp.io description: Sandbox Server - url: http://localhost:3001 description: Local Live Server - url: http://localhost:3003 description: Local Sandbox Server security: [] tags: - name: Health description: 서버 상태 확인 - name: Client Campaign description: 캠페인 조회 (Client API) - name: Client Creator description: 크리에이터 조회 (Client API) - name: Client Coupon description: 쿠폰 유효성 검사 (Client API) - name: Client Sponsor description: 부스트 상태 조회 — Sponsor API (Client API) - name: Server Campaign description: 캠페인 조회 (Server API) - name: Server Creator description: 크리에이터 조회 (Server API) - name: Server Coupon description: 쿠폰 관리 (Server API) - name: Server Sponsor description: 부스트 관리 — Sponsor API (Server API) - name: Server Payment description: 결제 관리 (Server API) - name: Server Playtime description: 플레이타임 세션 관리 (Server API) - name: Server Webhook description: 웹훅 관리 (Server API) - name: Server Webview description: WebView 관리 (Server API) paths: /v1/server/playtime/sessions: post: tags: - Server Playtime summary: 플레이타임 세션 기록 description: > 단일 플레이타임 세션을 기록합니다. **자동 귀속:** - `campaignId` 미지정 시 프로젝트의 활성 캠페인 스폰서로 자동 귀속 **멱등성:** - 고유 키는 `projectId` + `sessionId` 입니다 - 중복 `sessionId`는 에러가 아닙니다: 기존 row가 유지되며 응답의 `recorded` 값이 `false`로 반환됩니다 operationId: serverCreatePlaytimeSession requestBody: required: true content: application/json: schema: allOf: - $ref: '#/components/schemas/CreatePlaytimeSessionRequest' - type: object properties: callbackId: type: string description: 웹훅 추적용 ID (이 요청으로 발생하는 웹훅 이벤트에 포함됨) isTest: type: boolean default: false description: 테스트 모드 (실제 데이터 생성 안 함) responses: '200': description: 성공 content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/PlaytimeSession' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimited' security: - ServerAuth: [] components: schemas: CreatePlaytimeSessionRequest: type: object required: - sessionId - userId - durationSeconds - startedAt - endedAt properties: sessionId: type: string description: 클라이언트에서 생성한 고유 세션 ID userId: type: string description: 사용자 ID durationSeconds: type: integer minimum: 1 description: 세션 지속 시간 (초) startedAt: type: string format: date-time description: | 세션 시작 시각 (ISO 8601 UTC 형식) - 형식: `YYYY-MM-DDTHH:mm:ss.sssZ` - 예시: `2024-01-15T10:30:00.000Z` endedAt: type: string format: date-time description: | 세션 종료 시각 (ISO 8601 UTC 형식, `startedAt` 이상이어야 함) - 형식: `YYYY-MM-DDTHH:mm:ss.sssZ` - 예시: `2024-01-15T11:00:00.000Z` campaignId: type: string description: 캠페인 ID (선택). 미지정 시 프로젝트의 활성 캠페인 스폰서로 자동 귀속 creatorKey: type: string pattern: ^[A-Z0-9]{5}$ description: 크리에이터 키 (선택, 정확히 5자리 대문자 영숫자) platform: type: string enum: - iOS - Android - Web - Roblox - Other description: 플레이타임 플랫폼 (선택, 미지정 시 서버에서 `Other`로 기본 설정) metadata: type: object description: 임의의 키/값 메타데이터 additionalProperties: true PlaytimeSession: type: object description: 기록된 플레이타임 세션 properties: sessionId: type: string userId: type: string durationSeconds: type: integer recorded: type: boolean description: | 세션이 새로 기록되었는지 여부. - `true`: 새 세션 row가 생성됨 - `false`: 중복 `sessionId`가 무시되고 기존 row가 유지됨 (에러 아님) createdAt: type: string format: date-time ValidationError: type: object required: - status - error - message - code - details properties: status: type: integer example: 400 error: type: string example: Bad Request message: type: string example: Validation failed code: type: string example: VALIDATION_ERROR details: type: array items: type: object properties: path: type: string description: 오류가 발생한 필드 경로 message: type: string description: 오류 메시지 example: - path: userId message: Required - path: amount message: Expected number, received string Error: type: object required: - status - error - message - code properties: status: type: integer description: HTTP 상태 코드 error: type: string description: HTTP 상태 이름 message: type: string description: 상세 에러 메시지 code: type: string description: | 에러 코드: - `VALIDATION_ERROR`: 요청 파라미터 검증 실패 - `BAD_REQUEST`: 잘못된 요청 - `UNAUTHORIZED`: 인증 실패 (API 키 오류) - `FORBIDDEN`: 권한 없음 - `NOT_FOUND`: 리소스를 찾을 수 없음 - `CONFLICT`: 중복 리소스 (이미 존재) - `INTERNAL_ERROR`: 서버 내부 오류 details: type: array description: 검증 오류 상세 (VALIDATION_ERROR의 경우) items: type: object properties: path: type: string message: type: string example: status: 404 error: Not Found message: 'Payment not found: txn-12345' code: NOT_FOUND responses: ValidationError: description: 요청 파라미터 검증 실패 content: application/json: schema: $ref: '#/components/schemas/ValidationError' Unauthorized: description: 인증 실패 (API 키 오류) content: application/json: schema: $ref: '#/components/schemas/Error' example: status: 401 error: Unauthorized message: Invalid API key code: UNAUTHORIZED Forbidden: description: 권한 없음 (Client 키로 Server API 접근 등) content: application/json: schema: $ref: '#/components/schemas/Error' example: status: 403 error: Forbidden message: Access denied code: FORBIDDEN RateLimited: description: 요청이 너무 많음 (요청 제한 초과) content: application/json: schema: $ref: '#/components/schemas/Error' example: status: 429 error: Too Many Requests message: Rate limit exceeded code: RATE_LIMITED securitySchemes: ServerAuth: type: http scheme: bearer description: 'Server API Key (format: {keyId}:{secret})' ````