API Reference · 랭킹

실시간 랭킹 조회

캠페인의 실시간 랭킹을 me + Top N 형태로 응답합니다. 상시(always_on) 캠페인과 프로모션(promotion) 캠페인 모두 지원하며, 동점자는 먼저 달성한 사용자 순으로 정렬됩니다.

GET/api/v1/campaigns/{campaign_id}/rankings/live

인증

아래 두 형식을 모두 지원합니다 (영구 호환).

Authorization: Bearer <publisher_secret> (권장)
Authorization: Basic base64(publisher_id:publisher_secret)

요청 파라미터

campaign_id (path, uuid v7, required) — 조회할 캠페인 식별자입니다.
publisher_user_id (query, string, required) — 본인 순위(me)를 조회할 매체 사용자 식별값입니다.
type (query, enum, optional) — 랭킹 집계 기준입니다. 생략 시 캠페인에 설정된 default_ranking_type 이 적용됩니다.
- score_best: 게임 최고 점수 기준
- score: 전체 기간 완료 점수 합계 기준
- score_daily_sum: KST 일일 완료 점수 합계 기준
- point: 적립 포인트 기준
- level: 게임 레벨 기준
- stage: 게임 최고 스테이지 기준
- event: 사전에 정의한 게임 미션 이벤트 최초 달성 선착순 기준
- event_sum: 사전에 정의한 게임 미션 이벤트 달성 횟수 기준
top (query, integer, optional, default=100, max=100) — 반환할 Top N 등수 입니다. 동률이 있을 경우 동률까지 포함해서 반환합니다. 동점자가 있어 등수와 로우수가 같지 않을 수 있습니다.

요청예시

shell

curl -H "Authorization: Bearer sk_pub_prod_4eC39HqLyjWDarjtT1zdp7dc" \
     "https://added.blomics.net/api/v1/campaigns/{campaign_id}/rankings/live?publisher_user_id=u_123&type=score_best&top=10"

응답 필드

campaign_id (uuid v7) — 요청한 조회 캠페인 식별자입니다.
ranking_type (enum) — 반영된 8개 타입 (score_best | score | score_daily_sum | point | level | stage | event | event_sum) 중 하나입니다.
as_of (ISO 8601 UTC) — 집계 기준 시작으로 현재는 실시간으로 제공합니다.
me (object) — 요청한 매체사 사용자의 랭킹입니다. 등록돼있지만 플레이 이력이 없는 유저는 rank=0, value=0 이 반환됩니다.
- rank — 랭킹순위입니다.
- value — 랭킹 유형에 따른 기준 값입니다. stage는 최고 스테이지 정수를 변환 없이 반환합니다. event만 최초 달성 시각의 10자리 Unix 초로 변환하며 JavaScript에서는 new Date(value * 1000)을 사용합니다.
- publisher_user_id — 매체사 사용자 식별값입니다.
- nickname (string | null) — 매체사 사용자 닉네임입니다. 세션 발급 시 닉네임을 전달하지 않은 사용자는 null 입니다.
top (array) — 지정한 등수까지의 실시간 랭킹으로 최대 300개의 행까지만 제공합니다.
- rank — 랭킹순위입니다.
- value — 랭킹 유형에 따른 기준 값입니다. stage는 최고 스테이지 정수를 변환 없이 반환합니다. event만 최초 달성 시각의 10자리 Unix 초로 변환하며 JavaScript에서는 new Date(value * 1000)을 사용합니다.
- publisher_user_id — 매체사 사용자 식별값입니다.
- nickname (string | null) — 매체사 사용자 닉네임입니다. 세션 발급 시 닉네임을 전달하지 않은 사용자는 null 입니다.
truncated(boolean) — 동점자가 너무 많아 최대 행 300이 넘는 경우 true를 반환합니다. “일부 동점자가 표시되지 않았을 수 있음” 안내해주세요.
period (object, optional) — 프로모션 캠페인 응답에만 포함되는 슬라이스 윈도우입니다.
- from (ISO 8601 UTC) — 프로모션 start_at.
- to (ISO 8601 UTC) — 호출 시각 또는 프로모션 end_at.
is_closed (boolean, optional) — 프로모션 캠페인 응답에만 포함되며, 프로모션 종료 후 호출 시 true.

순위는 메트릭 value만으로 DENSE_RANK를 계산합니다. level/stage처럼 값이 같은 경우 달성 시각은 같은 순위 안의 표시 순서만 결정합니다.

응답예시 — 상시(always_on) 캠페인

json

{
  "campaign_id": "0193...",
  "ranking_type": "score_best",
  "as_of": "2026-04-24T22:01:05.000Z",
  "me": { "rank": 42, "value": 8700, "publisher_user_id": "p-9001", "nickname": "초코나라" },
  "top": [
    { "rank": 1, "value": 24800, "publisher_user_id": "p-100", "nickname": "랭킹1등" },
    { "rank": 2, "value": 21500, "publisher_user_id": "p-204", "nickname": null },
    { "rank": 2, "value": 21500, "publisher_user_id": "p-777", "nickname": "공동2등" },
    { "rank": 3, "value": 19000, "publisher_user_id": "p-305", "nickname": "랭킹3등" }
  ],
  "truncated": false
}

응답예시 — 프로모션(promotion) 캠페인

json

{
  "campaign_id": "0194...",
  "ranking_type": "score_best",
  "as_of": "2026-05-15T12:00:00.000Z",
  "me": { "rank": 7, "value": 12450, "publisher_user_id": "p-9001", "nickname": "초코나라" },
  "top": [
    { "rank": 1, "value": 24800, "publisher_user_id": "p-100", "nickname": "랭킹1등" },
    { "rank": 2, "value": 21500, "publisher_user_id": "p-204", "nickname": null }
  ],
  "truncated": false,
  "period": {
    "from": "2026-05-01T00:00:00.000Z",
    "to":   "2026-05-15T12:00:00.000Z"
  },
  "is_closed": false
}

릴레이 동작

콘텐츠사가 캠페인 등록 시 ranking_url 을 입력한 경우, ad.ded 는 호출을 콘텐츠사 서버로 릴레이하고 그 응답을 본 API 의 응답 스키마로 변환해 반환합니다. 그렇지 않으면 ad.ded 내부 집계 결과를 반환합니다. 매체사 클라이언트는 두 경로 모두 동일한 응답 형태를 받습니다.

프로모션 캠페인 동작

프로모션(promotion) 캠페인 ID 로 호출하면, 부모 상시(always_on) 캠페인의 데이터를 프로모션 start_at ~ end_at 윈도우로 슬라이스해 응답합니다. 시작 전 · 종료 후에도 200 OK 로 응답하며, 진행 중에는 period.to 가 호출 시각, 종료 후에는 end_at 으로 고정되고 is_closed = true 가 함께 반환됩니다.

에러처리

400 INVALID_PARAM — 필수 파라미터 및 파라미터 입력이 잘못된 경우.
401 UNAUTHORIZED — 자격증명이 실패한 경우.
404 NOT_FOUND — 잘못된 캠페인 또는 매체사 사용자 식별값일 경우, 혹은 랭킹을 제공하지 않는 캠페인(default_ranking_type 미설정)일 경우.
409 CAMPAIGN_EXPIRED / CAMPAIGN_PAUSED — 상시(always_on) 캠페인이 만료 또는 활성이 아닌 경우. 프로모션 캠페인은 시작 전 / 종료 후에도 200 OK 로 응답하므로 CAMPAIGN_EXPIRED 가 발생하지 않습니다 (CAMPAIGN_PAUSED 는 부모 상시 캠페인이 일시중지된 경우 동일하게 발생).
500 INTERNAL_ERROR — 릴레이 모드에서 콘텐츠의 ranking_config 형식이 잘못된 경우.
502 INTERNAL_ERROR — 릴레이 모드에서 콘텐츠사 서버 호출이 실패하거나(네트워크 오류·non-2xx·non-JSON) 응답 형식이 비정상인 경우.
504 INTERNAL_ERROR — 릴레이 모드에서 콘텐츠사 서버 응답이 타임아웃된 경우.