개발 가이드

콘텐츠사 연동

본 문서는 Blomics 리워드 광고 서비스의 콘텐츠를 연동하기 위한 콘텐츠 제공사용 기술 가이드입니다. 콘텐츠사는 이 문서를 참고하여 세션 검증, 이벤트 조회/저장 API 를 연동해주시기 바랍니다.

연동 전 준비사항

Blomics 연동을 시작하기 전에 다음 정보를 Blomics 담당자로부터 전달받아야 합니다.

provider_id — UUID. 콘텐츠사 식별자. 변경 불가.
provider_secret — 32-byte base64url(43자). 콘텐츠사 등록 시 1회 자동 발급.

콘텐츠사가 준비해야 할 것

콘텐츠 웹 애플리케이션 — 웹뷰에서 로드될 콘텐츠 페이지 (URL 등록 필요)
서버 API 연동 — 세션 검증, 이벤트 조회, 이벤트 저장 API 호출 구현

콘텐츠 페이지 리다이렉션

블로믹스 게이트웨이를 통해서 데이터베이스에 등록한 content_url 로 리다이렉션됩니다. 이때 session_id 를 QueryString 값으로 전달합니다.

http

GET {content_url}?session_id={uuid}

세션 검증 API

사용자가 콘텐츠 페이지에 진입하면, Blomics 서버가 URL 에 session_id 를 포함하여 전달합니다. 콘텐츠사 서버는 이 세션을 검증하여 사용자 정보를 확인합니다.

요청 예시

http

GET https://added.blomics.net/api/v1/sessions/{session_id}
Authorization: Bearer {provider_secret}

응답 예시

json

{
  "session_id": "0192...",
  "publisher_user_id": "user_12345",
  "content_id": "0193...",
  "publisher_id": "0194...",
  "expires_at": "2026-05-02T12:00:00Z"
}

이벤트 조회 API

캠페인에 등록된 이벤트 목록을 조회합니다. 콘텐츠 초기화 시 이벤트 목표를 설정하는 데 사용합니다.

요청 예시

http

GET https://added.blomics.net/api/v1/contents/{content_id}/events
Authorization: Bearer {provider_secret}

응답 예시

json

{
  "events": [
    {
      "event_id": "0194...",
      "event_type": "complete",
      "name": "콘텐츠 완료",
      "description": "콘텐츠 1회 플레이 완료",
      "point": 100
    },
    {
      "event_id": "0195...",
      "event_type": "all_clear",
      "name": "전체 클리어",
      "description": "모든 스테이지 클리어",
      "point": 500
    }
  ]
}

이벤트 저장 API

사용자가 이벤트를 달성하면 콘텐츠사 서버가 Blomics 서버에 보고합니다. v2 부터 엔드포인트는 content_id 단위 (POST /api/v1/contents/{content_id}/events) 이며 body 의 event_type 으로 매칭합니다.

요청 예시

http

POST https://added.blomics.net/api/v1/contents/{content_id}/events
Authorization: Bearer {provider_secret}
Content-Type: application/json

{
  "session_id": "0192...",
  "event_type": "complete",
  "value": 100
}

응답 예시

json

{
  "summary": { "matched_count": 1, "rejected_count": 0 },
  "legs": [
    {
      "campaign_id": "0193...",
      "event_id": "0194...",
      "point": 100,
      "reject_reason": null
    }
  ]
}

웹뷰 연동

웹뷰가 네이티브 앱에서 정상 동작하려면 별도의 설정이 필요합니다. 상세 내용은 웹뷰 연동를 참고해주세요.

콘텐츠사 API

콘텐츠 클라이언트는 매체사로부터 전달받은 session_token(sess_*) 으로 아래 엔드포인트를 호출합니다. 리포트는 콘텐츠사 시크릿(sk_prov_*) 으로 별도 호출합니다.

세션

매체사로부터 전달받은 세션의 정보를 조회합니다.

경품 프로모션을 운영하는 콘텐츠는 ?include=promo_claims 를 붙여 이 사용자가 당첨된 경품 목록을 함께 받습니다. 한 사용자가 동시에 둘 이상 당첨될 수 있으므로 배열이며, 항목마다 캠페인과 그 캠페인의 신청 페이지 URL 이 담깁니다 — 안내와 링크를 항목 단위로 다루세요. 당첨 판정은 서버가 하고, 클라이언트는 결과만 표시합니다. 세션 조회는 자주 호출되는 경로이므로 안내가 필요한 시점(부팅·화면 복귀)에만 붙이는 것을 권장합니다.