퀵스타트

승인된 파트너 상태에서 시작하여 10단계 만에 첫 스트림 재생과 이벤트 추적까지 완료합니다. 여기의 모든 작업은 샌드박스 (https://nu-signal-partners.vercel.app/v1)에서 실행됩니다. 샌드박스 가이드를 참고하세요.

먼저 샌드박스 기본 URL을 설정하세요. 승인 후 NU가 보내주는 org id와 부트스트랩 토큰을 추가합니다:

export NSP_BASE="https://nu-signal-partners.vercel.app/v1"
export NSP_ORG="org_xxxxxxxx"
export NSP_APPROVAL_TOKEN="nsp_appr_xxxxxxxxxxxxxxxx"

1. 조직 승인 받기

파트너 신청서를 제출합니다(유일하게 인증이 필요 없는 엔드포인트):

curl -X POST "$NSP_BASE/partner-applications" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Streaming",
    "service_type": "OTT",
    "contact_name": "Jin Park",
    "contact_email": "dev@acme.example",
    "target_territories": ["KR", "JP"],
    "expected_use_case": "Catalog licensing + VOD playback"
  }'

application_id를 받게 됩니다. NU가 조직을 검토하고 승인하며, 승인 전까지 인증된 호출은 organization_not_approved(403)를 반환합니다. 이 엔드포인트는 2단계의 부트스트랩 호출과 마찬가지로 IP당 분당 20회 요청으로 속도 제한됩니다.

2. 첫 샌드박스 키 발급하기

승인되면 일회성 승인 토큰을 받게 됩니다. 이를 API 키 엔드포인트를 통해 접두사 nsp_test_의 샌드박스 키로 교환하세요. 시크릿은한 번만 표시되므로 시크릿 매니저에 저장하세요. 별도의 웹 콘솔은 없으며, 동일한 API를 통해 키를 직접 회전하고 폐기합니다.

curl -X POST "$NSP_BASE/api-keys/bootstrap" \
  -H "Content-Type: application/json" \
  -d "{ \"approval_token\": \"$NSP_APPROVAL_TOKEN\" }"

# Copy data.secret from the 201 response:
export NSP_KEY="nsp_test_xxxxxxxxxxxxxxxx"

3. 최소 권한으로 스코프 지정하기

부트스트랩 키를 사용해 더 좁은 범위의 연동 키를 생성하세요. 필요한 스코프만 부여합니다. 이 가이드에서는 catalog:read, playback:token, events:write입니다. api_keys:write 권한을 가진 서버 사이드 관리용 키는 별도로 보관하고, 선택적으로 각 키에 허용 오리진/IP를 고정하세요. API 키를 참고하세요.

4. Postman 컬렉션 다운로드

공개된 Postman 컬렉션 / OpenAPI (openapi/partner-api.yaml)를 가져온 뒤 base, key, org 변수를 위 값으로 설정하세요.

5. 카탈로그 타이틀 목록 조회

curl "$NSP_BASE/catalog/titles?territory=KR&limit=5" \
  -H "Authorization: Bearer $NSP_KEY" \
  -H "X-NU-Partner-Id: $NSP_ORG"

X-NU-Partner-Id는 선택 사항입니다. 전달할 경우 키가 발급된 org와 일치해야 하며(일치하지 않으면 호출이 거부됨), 필수는 아닙니다 — org는 키에서 도출됩니다. 아래 curl 예시는 명확성을 위해 이를 전달합니다.

data[]에서 title_id를 하나 고른 다음, 해당 에피소드를 조회하고(GET /catalog/titles/{title_id}/episodes)episode_id를 복사하세요. 카탈로그 API를 참고하세요.

6. 재생 인가하기

viewer_id_hash는 시청자 id에 솔트를 더해 직접계산한 SHA-256 값이며, 절대 원시 PII가 아닙니다. 선택적으로 비식별(non-PII) preferences(선호 언어/장르, 자막/오디오 기본값, 자동 재생)를 전달하여 웹뷰 플레이어를 개인화할 수 있습니다.

curl -X POST "$NSP_BASE/playback/tokens" \
  -H "Authorization: Bearer $NSP_KEY" \
  -H "X-NU-Partner-Id: $NSP_ORG" \
  -H "Content-Type: application/json" \
  -d '{
    "title_id": "ttl_abc",
    "episode_id": "ep_001",
    "viewer_id_hash": "9f86d081884c7d65...",
    "country": "KR",
    "device": "web",
    "origin": "https://app.acme.example",
    "preferences": { "subtitle_language": "ko", "autoplay_next": true },
    "expires_in": 1800
  }'

샌드박스에서는 샌드박스에 노출된 타이틀만 재생되며 라이선스 계약이 필요하지 않습니다 — 다만 권리 게이트는 여전히 적용됩니다. 타이틀에는 파트너에게 노출되고 만료되지 않은 권리 패키지가 있어야 하며, country를 전달하는 경우 해당 권리의 지역 범위에 포함되어야 합니다 (그렇지 않으면 세션이 territory_not_allowed로 차단됩니다). 응답은 playback_session_id, expires_at, 호스팅된 webview_url, 서명된 hls / dash URL을 담은 manifest 객체, 그리고tracking 객체 (event_endpoint + required_events)를 반환합니다. 재생 API를 참고하세요.

7. 재생하기

동일한 세션에 대한 두 가지 동등한 방법:

웹뷰 (권장): webview_url을 WebView(WKWebView / android.webkit.WebView) 또는 <iframe>에서 엽니다. 플레이어를 직접 연결할 필요가 없으며, preferences가 자동으로 적용됩니다. 이 URL은 서명된 토큰을 포함하므로 시크릿으로 취급하세요.
자체 플레이어 사용: 임의의 HLS 플레이어(hls.js, AVPlayer, ExoPlayer)를manifest.hls로 지정하세요. CDN은 세그먼트를 제공하기 전에 서명과 TTL을 검증하며, 마스터 파일은 절대 노출되지 않습니다.

8. 이벤트 전송하기

curl -X POST "$NSP_BASE/events" \
  -H "Authorization: Bearer $NSP_KEY" \
  -H "X-NU-Partner-Id: $NSP_ORG" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "evt_acme_0001",
    "event_type": "EPISODE_STARTED",
    "title_id": "ttl_abc",
    "episode_id": "ep_001",
    "playback_session_id": "pbs_123",
    "occurred_at": "2026-06-24T00:00:00Z"
  }'

200과 함께 { data: { event_id, status: "validated", received_at } }을 반환합니다. event_id는 org별로 고유하며 멱등적입니다 — 재전송 시 409 duplicate_event_id를 반환합니다. 이벤트 API를 참고하세요.

9. 수집 결과 확인하기

응답 상태가 validated인지 확인하세요. 오류 응답에서 반환되는request_id를 로그에 저장하고, 안정적인event_id 값을 사용하여 재시도 시 중복 집계 대신 duplicate_event_id가 반환되도록 하세요.

10. 프로덕션 키 요청하기

연동이 완료되면 프로덕션 체크리스트를 진행하세요. 프로덕션 라이선스 계약을 체결하여 status가 active가 되고 production_api_enabled가 true가 될 때까지 진행한 뒤 (라이선스 API),nsp_live_ 키를 요청하고 allowed_origins/allowed_ips를 설정한 다음,NSP_BASE를 https://nu-signal-partners.vercel.app/v1로 전환하세요.