봇, 오버레이, 스트리밍 도구를 구축하고 D1Arena 데이터와 통합하세요.
인증
모든 API 요청에는 X-API-Key / Authorization: Bearer 헤더에 전달된 API 키가 필요합니다.
API 키를 생성하려면 대시보드에서 개발자 설정로 이동하세요. 최대 5개의 키를 가질 수 있습니다.
Retry-After 헤더와 함께 429 Too Many Requests를 반환합니다.
기본 URL
모든 엔드포인트는 JSON을 반환합니다. 페이지가 매겨진 엔드포인트에는 current_page, last_page 및 total이 포함된 meta 객체가 포함됩니다.
스트림
| 매개변수 | 유형 | 설명 |
|---|---|---|
category_id | integer | 게임/카테고리 ID로 필터링 |
limit | integer | 페이지당 결과(기본값: 20) |
page | integer | 페이지 번호 |
카테고리
| 매개변수 | 유형 | 설명 |
|---|---|---|
search | string | 이름으로 카테고리 필터링 |
limit | integer | 페이지당 결과(기본값: 50) |
사용자
클립
| 매개변수 | 유형 | 설명 |
|---|---|---|
streamer_id | integer | 스트리머의 사용자 ID로 클립 필터링 |
category_id | integer | 게임/카테고리 ID로 필터링 |
limit | integer | 페이지당 결과(기본값: 20) |
토너먼트
| 매개변수 | 유형 | 설명 |
|---|---|---|
status | string | 상태별로 필터링(예: open, in_progress, completed) |
league_id | integer | 리그 ID로 필터링 |
limit | integer | 페이지당 결과(기본값: 20) |
ELO 순위
| 매개변수 | 유형 | 설명 |
|---|---|---|
category_id | integer | 게임/카테고리 ID로 필터링 |
limit | integer | 결과 수(기본값: 50) |
리그
| 매개변수 | 유형 | 설명 |
|---|---|---|
status | string | 리그 상태로 필터링 |
category_id | integer | 게임/카테고리 ID로 필터링 |
limit | integer | 페이지당 결과(기본값: 20) |
오류 응답
모든 오류는 일관된 JSON 봉투를 반환합니다. error 객체에는 항상 기계가 읽을 수 있는 code와 사람이 읽을 수 있는 message가 포함되어 있습니다.
상태 코드
오류 코드 참조
| 코드 | HTTP 상태 | 설명 |
|---|---|---|
invalid_api_key | 401 | API 키가 누락되었거나 형식이 잘못되었거나 존재하지 않습니다. |
api_key_disabled | 403 | API 키가 취소되거나 비활성화되었습니다. |
not_found | 404 | 요청한 리소스를 찾을 수 없습니다 |
validation_error | 422 | 하나 이상의 요청 매개변수가 잘못되었습니다. |
rate_limited | 429 | 이 API 키에 대한 요청 비율 제한이 초과되었습니다. |
server_error | 500 | 내부 서버 오류 - 다시 시도하거나 지원팀에 문의하세요. |
비율 제한
API 요청은 API 키별로 속도가 제한됩니다. 제한을 초과하면 요청은 Retry-After 헤더와 함께 429 Too Many Requests를 반환합니다.
등급별 한도
| 계층 | 요청/분 (기본) | 최대 키 |
|---|---|---|
| 기동기 (무료) | 60 | 5 |
| 프로 | 60 | 5 |
| 궁극의 | 60 | 5 |
| 파트너 | 60 | 5 |
속도 제한 헤더
API 요청은 API 키별로 속도가 제한됩니다. 제한을 초과하면 요청은 Retry-After 헤더와 함께 429 Too Many Requests를 반환합니다.
| 헤더 | 설명 |
|---|---|
Retry-After | 재시도 전 대기 시간(429개 응답에만 표시됨) |
모범 사례
- Cache responses locally — stream and tournament data doesn't change every second.
- 엔드포인트를 폴링하는 대신 실시간 이벤트를 위해 webhooks를 구독하세요.
- 가능한 경우 일괄 요청 — 필터 매개변수를 사용하면 더 적은 호출로 필요한 것을 정확하게 얻을 수 있습니다.
웹후크(EventSub)
폴링 대신 실시간 푸시 알림을 구독하세요. 이벤트가 발생하면 D1Arena는 HMAC-SHA256으로 서명된 JSON 페이로드와 함께 HTTP POST를 콜백 URL로 보냅니다.
설정
개발자 설정에서 웹훅 구독을 생성합니다. 각 구독에는 다음이 필요합니다.
- 콜백 URL — 서버에서 공개적으로 액세스 가능한 HTTPS 엔드포인트.
- 이벤트 — 구독할 하나 이상의 이벤트 유형입니다.
You'll receive a whsec_ signing secret upon creation. Store it securely — it's shown only once.
페이로드 형식
모든 웹훅 전달은 다음 구조의 JSON 본문을 보냅니다.
헤더
각 배송에는 라우팅 및 확인을 위한 다음 헤더가 포함됩니다.
| 헤더 | 설명 |
|---|---|
Content-Type | application/json |
X-D1Arena-Event | 이벤트 유형(예: stream.online) |
X-D1Arena-Signature | 원시 요청 본문의 HMAC-SHA256 16진수 다이제스트 |
X-D1Arena-Signature-Version | 서명 키 형식: 현재 구독의 경우 v2, 레거시 구독의 경우 v1-hashed-secret |
X-D1Arena-Delivery-Id | 고유한 전달 UUID — 중복 제거에 사용 |
X-D1Arena-Timestamp | 이벤트가 전송된 시점의 Unix 타임스탬프 |
서명 확인
웹훅을 처리하기 전에 항상 X-D1Arena-Signature 헤더를 확인하세요. 서명은 HMAC-SHA256(raw_body, webhook_secret)로 계산됩니다.
v2 전달의 경우 구독이 생성될 때 표시된 whsec_ 비밀을 사용합니다. 사전 업그레이드 v1-hashed-secret 전달의 경우 먼저 원래 비밀에서 SHA256(whsec_secret)를 계산하고 결과 소문자 16진수 다이제스트를 HMAC 키로 사용합니다. v2로 이동하려면 구독을 다시 만드세요.
이용 가능한 이벤트
| 이벤트 | 설명 |
|---|---|
| stream.online | 스트리머가 생방송을 시작했습니다. |
| stream.offline | 스트리머가 오프라인 상태가 되었습니다. |
| channel.follow | 사용자가 채널을 팔로우했습니다. |
| channel.subscribe | 채널의 새로운 후원자 구독 |
| channel.tip | 스트리머에게 팁이 전송되었습니다. |
| tournament.started | 토너먼트 매치 플레이가 시작되었습니다 |
| tournament.ended | 토너먼트가 종료되었습니다 |
| tournament.match.completed | 경기 결과가 기록되었습니다 |
| clip.created | 실시간 스트림에서 새 클립이 생성되었습니다. |
| overdrive.started | D1 Frenzy가 채널에서 시작되었습니다. |
| overdrive.level_up | D1 Frenzy가 다음 단계로 발전했습니다. |
| overdrive.ended | D1 Frenzy 완료 또는 만료 |
이벤트 페이로드 예
stream.online
stream.offline
channel.follow
channel.tip
tournament.match.completed
clip.created
배송 및 재시도 정책
| 시도 | 지연 | 메모 |
|---|---|---|
| 1위(이니셜) | 즉시 | 이벤트 발생 후 몇 초 이내에 전송됨 |
| 2번째(재시도) | 30초 | 첫 번째 시도가 실패하거나 시간 초과된 경우 |
| 3번째(재시도) | 2분 | 지수 백오프 |
| 4위(최종) | 10분 | 실패로 표시하기 전 마지막 시도 |
2xx status within 10초. Non-2xx responses or timeouts trigger a retry. After 10연속 실패, the subscription is automatically disabled. You'll receive an email notification and can re-enable it in 개발자 설정.
모범 사례
- 항상 서명을 확인하세요. 스푸핑된 이벤트를 방지하기 위해 페이로드를 처리하기 전에.
- 중복 제거를 위해 배달 ID 사용 — 재시도 시에는 동일한 ID가 전송되므로 이중 처리를 방지하려면 처리된 ID를 저장하세요.
- 신속한 응답, 비동기식 처리 — 즉시
200 OK를 반환하고 백그라운드 작업에서 비즈니스 로직을 처리합니다. - HTTPS 엔드포인트만 사용 — 웹훅 URL은 TLS를 사용해야 합니다. HTTP 콜백이 거부됩니다.
- 알 수 없는 이벤트를 적절하게 처리 — 새로운 이벤트 유형이 추가될 수 있습니다. 오류가 아닌 인식할 수 없는 이벤트의 경우
200를 반환합니다.
D1 프렌지
D1 Frenzy는 스트리머가 생방송 중일 때 빠른 팁과 구독을 통해 촉발됩니다. 목표가 증가하면서 5단계로 진행됩니다.
GET /api/overdrive/{streamerId}
스트리머를 위한 활성 D1 Frenzy를 얻으세요. 없는 경우 {"active": false}을 반환합니다.
레벨 목표
| 레벨 | 포인트 |
|---|---|
| 1 | 100 |
| 2 | 250 |
| 3 | 500 |
| 4 | 1,000 |
| 5 | 2,000 |
D1 프렌지 — 포인트: 팁 $1 → 100; 구독 500 × 계층. 기간: 5 분; 쿨다운: 30 분.
확장 SDK
스트리머가 채널 페이지에 설치할 수 있는 맞춤형 패널 및 오버레이 확장 프로그램을 구축하세요. 확장 프로그램은 샌드박스 iframe에서 실행되며 postMessage을 통해 호스트 페이지와 통신합니다.
시작하기
- 개발자 설정에서 API 키를 생성합니다.
- 도메인에서 호스팅되는 독립형 HTML 페이지로 확장 프로그램을 구축하세요(HTTPS 필요).
- 검토를 위해 내 확장 프로그램 섹션에 제출하세요.
- 승인되면 스트리머는 Extension Marketplace에서 이를 설치할 수 있습니다.
확장 유형
| 유형 | 위치 | 행동 |
|---|---|---|
panel | 스트림 플레이어 아래 | 스트림이 실시간일 때 표시됩니다. 전체 너비 카드, 기본 높이 300px. |
overlay | 비디오 플레이어 위에서 | 실시간으로 표시됩니다. 오버레이 위치 지정 도구를 통해 스트리머가 제어하는 위치/크기. |
포스트메시지 API
확장 프로그램은 로드될 때 자동으로 컨텍스트 데이터를 받습니다. 다음 이벤트를 구현하십시오.
모든 메시지에 대해 정확한 D1Arena 상위 원본을 사용하세요. 공식 SDK은 임베딩 페이지에서 이 출처를 자동으로 파생하고 유효성을 검사합니다.
확장 iframe은 의도적으로 불투명한 샌드박스 원본을 사용하므로 D1Arena 호스트는 등록된 iframe 창을 정확하게 인증합니다. 확장 코드는 컨텍스트를 수락하기 전에 상위 창과 정확한 D1Arena 출처를 인증해야 합니다.
1. 신호 준비
2. 컨텍스트 수신
3. 작업 보내기(선택 사항)
권한 범위
확장 프로그램에 필요한 데이터를 선언하세요. 검토자는 코드가 선언된 권한과 일치하는지 확인합니다.
| 범위 | 다음에 대한 액세스 권한을 부여합니다. |
|---|---|
read:stream | 스트림 상태, 제목, 카테고리 |
read:viewers | 시청자 수 및 목록 |
read:chat | 채팅 메시지(푸셔 채널을 통해) |
read:clips | /api/clips/{slug}를 통한 채널 클립 |
read:tournaments | /api/active-match/{id}를 통한 활성 경기 정보 |
read:channel | 채널 프로필, 팔로어, 일정 |
보안 요구 사항
sandbox="allow-scripts"을 사용하여 샌드박스 처리된 iframe에서 실행됩니다. 귀하의 확장 프로그램 할 수 없다은 쿠키, localStorage에 액세스하거나 d1arena.com에 인증된 요청을 보냅니다.
- 공개 HTTPS 필요 — iframe URL은 TLS을 사용해야 하며 공용 네트워크 주소로만 확인되어야 합니다.
- 사람이 읽을 수 있는 소스 — 난독화되거나 축소된 전용 JavaScript가 없습니다. 검토자는 코드를 읽을 수 있어야 합니다.
- 외부 스크립트 로딩 없음 귀하의 제출물에 선언되지 않은 한. CDN 라이브러리(jQuery, Chart.js 등)는 괜찮습니다.
- 데이터 유출 없음 — 확장 프로그램은 시청자 데이터를 제3자 분석 또는 추적 서비스로 전송해서는 안 됩니다.
- 콘텐츠 정책 — 광고, NSFW 콘텐츠, 암호화폐 채굴 또는 악의적인 행동이 없습니다.
검토 과정
| 상태 | 의미 |
|---|---|
| pending | 제출되었으며 관리자 검토를 기다리고 있습니다(일반적으로 영업일 기준 1~3일). |
| approved | 확장 마켓플레이스에서 승인되고 표시됩니다. |
| rejected | 이유로 거부되었습니다. 문제를 수정하고 다시 제출하세요. |
| suspended | 정책 위반으로 인해 일시적으로 삭제되었습니다. 지원팀에 문의하세요. |
버전 업데이트
승인된 확장 프로그램을 업데이트하려면 현재 버전을 삭제하고 버전 번호가 증가된 새 버전을 제출하세요. 새 버전은 다시 검토를 거칩니다.
변경 내역
API 변경 사항 및 새로운 기능을 추적합니다. 의미 체계 버전 관리를 따르고 주요 변경 사항을 최소 30일 전에 발표합니다.
- API 키 인증이 포함된 최초 공개 API 릴리스입니다.
- 스트림: 실시간 스트림을 나열하고 슬러그별로 스트리머 세부정보를 가져옵니다.
- 카테고리: 모든 게임 카테고리를 검색하고 나열합니다.
- 사용자: 경쟁 통계, ELO 등급 및 메달 개수가 포함된 공개 프로필입니다.
- 클립: 스트리머/크리에이터 정보가 포함된 클립 세부정보를 탐색하고 검색합니다.
- 토너먼트: 목록을 작성하고, 상태/리그별로 필터링하고, 참가자 수를 확인하세요.
- ELO 리더보드: 글로벌 및 카테고리별 순위 리더보드입니다.
- 리그: 순위 및 포인트 분석이 포함된 리그를 나열합니다.
- D1 Frenzy: 모든 스트리머의 실시간 Frenzy 상태입니다.
- 웹후크(EventSub): 스트림, 채널, 토너먼트, 클립, Frenzy 이벤트를 포함한 12가지 이벤트 유형입니다.
- 비율 제한
도움이 필요하신가요?
API에 대한 질문이 있으신가요? 문의하기.