快速开始

通过十个步骤，从获批合作伙伴完成首次流播放和事件追踪。此处所有操作均在 Sandbox（https://signal-partners.newunivers.ai/v1）中运行。参见 Sandbox 指南。

首先设置基础 URL。组织 ID 和密钥来自批准领取及 bootstrap 响应：

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. 使用最小权限设置作用域

使用 bootstrap 密钥创建范围更窄的集成密钥，只授予本指南所需的 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 个小写十六进制字符；绝不能是原始 PII。可选发送非 PII 的 preferences 来个性化托管 WebView。

不要复用示例值。请在服务器端使用合作伙伴秘密持有的盐计算哈希。

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（推荐）：在 WebView（WKWebView/android.webkit.WebView）或 <iframe> 中打开 webview_url。无需播放器集成，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。