빠른 시작

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

먼저 기본 URL을 설정하세요. 조직 ID와 키는 승인 클레임 및 부트스트랩 응답에서 얻습니다:

export NSP_BASE="https://signal-partners.newunivers.ai/v1"

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",
    "privacy_consent": true,
    "target_territories": ["KR", "JP"],
    "expected_use_case": "Catalog licensing + VOD playback"
  }'

응답의 application_reference와 status_token을 즉시 안전한 시크릿 저장소에 보관하세요. 상태 토큰은 한 번만 표시되며 URL이나 로그에 넣지 마세요. 같은 이메일로 24시간 내 다시 제출하면 새 신청 대신 기존 application_id를 반환합니다. NU가 조직을 검토하는 동안 상태 호출을 폴링하세요.

상태가 approved이고 claim_available이 true가 된 뒤 클레임을 정확히 한 번 실행하세요.

export NSP_APPLICATION_REFERENCE="nsp_app_..."
export NSP_STATUS_TOKEN="nsp_ast_..."

curl -X POST "$NSP_BASE/partner-applications/status"   -H "Content-Type: application/json"   -d "{"application_reference":"$NSP_APPLICATION_REFERENCE","status_token":"$NSP_STATUS_TOKEN"}"

curl -X POST "$NSP_BASE/partner-applications/claim"   -H "Content-Type: application/json"   -d "{"application_reference":"$NSP_APPLICATION_REFERENCE","status_token":"$NSP_STATUS_TOKEN"}"

export NSP_APPROVAL_TOKEN="nsp_appr_..."

2. 첫 Sandbox 키 발급

승인 후 /partner-applications/claim에서 한 번 받은 승인 토큰을 nsp_test_ 접두사의 Sandbox 키로 교환하세요. 시크릿은 한 번만 표시되므로 시크릿 매니저에 저장하세요. 읽기 전용 파트너 포털에서 같은 키로 상태를 볼 수 있지만 키 생성, 회전 및 폐기는 API에서만 수행합니다.

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

export NSP_ADMIN_KEY="nsp_test_xxxxxxxxxxxxxxxx"

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

부트스트랩 키로 이 가이드에 필요한 catalog:read, playback:token, events:write만 가진 좁은 연동 키를 생성하세요. api_keys:write를 가진 서버 측 관리 키는 별도로 보관하고 선택적으로 각 키에 허용 오리진과 IP를 고정하세요. API 키를 참고하세요.

curl --fail-with-body -X POST "$NSP_BASE/api-keys" \
  -H "Authorization: Bearer $NSP_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "sandbox",
    "scopes": ["catalog:read", "playback:token", "events:write"]
  }'

export NSP_KEY="nsp_test_xxxxxxxxxxxxxxxx"

4. Postman 컬렉션 다운로드

Postman 컬렉션과 Sandbox 환경 파일을 다운로드하여 Postman에 가져온 뒤 base_url과 api_key를 위 값으로 설정하세요.

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

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

조직은 API 키에서 안전하게 도출되므로 X-NU-Partner-Id를 별도로 보낼 필요가 없습니다.

data[]에서 title_id를 고르고 GET /catalog/titles/{title_id}/episodes로 에피소드를 조회한 뒤 episode_id를 복사하세요. 카탈로그 API를 참고하세요.

6. 재생 인가

viewer_id_hash는 시청자 ID와 솔트로 직접 계산한 SHA-256입니다. Production은 64자의 소문자 16진수를 요구하며 원시 PII여서는 안 됩니다. 선택적으로 비PII preferences를 보내 호스팅 웹뷰를 개인화하세요.

샘플 값을 재사용하지 마세요. 파트너가 비밀로 보관하는 솔트로 서버에서 해시를 계산하세요.

export NSP_VIEWER_HASH="$(printf '%s' 'stable-viewer-id:replace-with-secret-salt' | sha256sum | cut -d' ' -f1)"

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

Sandbox 재생에는 라이선스 계약이 필요 없지만 권리 게이트는 적용됩니다. 타이틀에는 노출되고 만료되지 않은 권리 패키지가 필요하며 country를 보내면 허용 지역이어야 하고 그렇지 않으면 territory_not_allowed로 차단됩니다. 응답은 playback_session_id, expires_at, 호스팅된 webview_url, 서명된 hls/dash URL을 담은 manifest, event_endpoint와 required_events를 담은 tracking을 포함합니다. 재생 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 "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는 조직별로 고유하고 멱등이며 다시 보내면 409 duplicate_event_id를 반환합니다. 이벤트 API를 참고하세요.

9. 수집 결과 확인

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

10. Production 키 요청

연동을 마치면 프로덕션 체크리스트를 따르세요. Production 계약을 체결하여 status가 active이고 production_api_enabled가 true가 되게 한 뒤(라이선스 API) nsp_live_ 키를 요청하고 allowed_origins/allowed_ips를 설정한 다음 NSP_BASE를 https://signal-partners.newunivers.ai/v1로 전환하세요.