クイックスタート

承認済みパートナーから最初のストリーム再生とイベント追跡までを10ステップで進めます。すべてSandbox（https://signal-partners.newunivers.ai/v1）で実行します。Sandboxガイドを参照してください。

最初にベースURLを設定します。組織IDとキーは承認claimとブートストラップのレスポンスから取得します:

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の審査中は状態をポーリングします。

statusがapprovedでclaim_availableがtrueになった後、claimを正確に一度実行してください。

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とsaltから自社で計算するSHA-256です。Productionでは64文字の小文字16進数が必要で、生のPIIは禁止です。任意の非PII preferencesでホスト型WebViewをパーソナライズできます。

サンプル値を再利用しないでください。パートナーが秘密に保管するsaltでサーバー上にてハッシュを計算します。

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を含むmanifest、event_endpointとrequired_eventsを含むtrackingを返します。再生APIを参照してください。

7. 再生

同じセッションに対する2つの同等な方法から選びます:

ホスト型WebView（推奨）: 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チェックリストに従います。Production契約を締結してstatusをactive、production_api_enabledをtrueにし（ライセンスAPI）、nsp_live_キーを要求してallowed_origins/allowed_ipsを設定後、NSP_BASEをhttps://signal-partners.newunivers.ai/v1へ切り替えます。