# Stream Status API

使用 **Stream Status** 端点询问 DailyPlay 当前是否应显示 stream — 在您于网站上挂载 iframe、悬浮游玩按钮或自定义浮层之前。

这是**公开 GET**（无需 API key）。专为希望以下操作的站点与应用所有者设计：

- **仅在 stream 活跃时**显示 stream 浮层
- 在活动尚未开始或已结束时隐藏 Play 按钮
- 在没有已发布游戏时避免加载完整 stream 播放器

:::tip[轻量设计]
与完整 stream 播放器载荷不同，此端点**不**返回游戏配置或奖品，也**不**记录分析。优先用于可用性门控；仅在 `available` 为 `true` 时加载 stream URL。
:::

## 端点

```
GET https://app.dailyplay.ai/api/stream-status?org_slug=<org-slug>&stream_slug=<stream-slug>
```

| 参数 | 必填 | 说明 |
| ------------- | -------- | ------------------------------------------------ |
| `org_slug` | 是 | 组织 slug（来自 stream 分享 URL） |
| `stream_slug` | 是 | Stream slug（来自 stream 分享 URL） |

**Auth：** 无  
**CORS：** `Access-Control-Allow-Origin: *`（可安全从浏览器调用）  
**Cache：** `public, s-maxage=30, stale-while-revalidate=60` — 主机可约每 30 秒轮询一次

### 示例

```
https://app.dailyplay.ai/api/stream-status?org_slug=your-org&stream_slug=summer-campaign
```

## 响应

HTTP `200` 且 `success: true` 表示请求已处理。使用 **`data.available`** 决定是否显示 stream UI。

### 可用

```json
{
  "success": true,
  "data": {
    "available": true,
    "reason": null,
    "total_games": 4,
    "starts_at": null,
    "ends_at": null,
    "timezone": "UTC",
    "server_time": "2026-10-15T07:23:43.597Z",
    "stream": {
      "slug": "summer-campaign",
      "status": "active"
    },
    "organization": {
      "slug": "your-org"
    }
  }
}
```

### 不可用

```json
{
  "success": true,
  "data": {
    "available": false,
    "reason": "stream_inactive",
    "total_games": 0,
    "starts_at": null,
    "ends_at": null,
    "timezone": "UTC",
    "server_time": "2026-10-15T07:23:43.597Z",
    "stream": {
      "slug": "summer-campaign",
      "status": "draft"
    },
    "organization": {
      "slug": "your-org"
    }
  }
}
```

### 响应字段

| 字段 | 类型 | 说明 |
| ------------------------- | -------------- | ----------- |
| `available` | boolean | 访客可游玩 stream 时为 `true` |
| `reason` | string \| null | stream 不可用的原因（可用时为 `null`） |
| `total_games` | number | stream 上**已发布**游戏的数量（非公开时为 `0`） |
| `starts_at` / `ends_at` | string \| null | 日程边界，ISO UTC（来自 stream 时区） |
| `timezone` | string | 用于日程检查的 stream 时区 |
| `server_time` | string | 决策时的服务器时钟（ISO UTC） |
| `stream.slug` / `status` | string | Stream 标识与状态 |
| `organization.slug` | string | 组织 slug |

### 不可用原因

| `reason` | 含义 |
| -------------------- | ------- |
| `not_public` | Stream 非公开（不泄露详情） |
| `stream_inactive` | Stream 状态不是 `active`（例如 draft / archived） |
| `stream_not_started` | 当前时间早于 `starts_at` |
| `stream_ended` | 当前时间晚于 `ends_at` |
| `no_games` | Stream 活跃/公开但没有已发布游戏 |

### 错误响应

| 代码 | 何时 |
| ---- | ---- |
| `400` | 缺少 `org_slug` 或 `stream_slug` |
| `404` | 未找到组织或 stream |
| `405` | 非 `GET` / `OPTIONS` 的方法 |
| `500` | 服务器错误 |

```json
{
  "success": false,
  "error": "Stream not found"
}
```

---

## 何时 stream「可用」？

以下全部必须为真：

1. Stream 存在于给定的 org slug 下
2. Stream 为**公开**
3. Stream 状态为 **`active`**
4. 若设置了开始时间，则已开始（按 stream 时区）
5. 若设置了结束时间，则尚未结束
6. 至少有一款**已发布**游戏附加到 stream

---

## 典型集成：门控浮层

站点所有者通常在 stream 上线前将悬浮游玩按钮或模态排除在 DOM 之外。

```html
<script>
  async function shouldShowStreamOverlay(orgSlug, streamSlug) {
    const url =
      "https://app.dailyplay.ai/api/stream-status" +
      `?org_slug=${encodeURIComponent(orgSlug)}` +
      `&stream_slug=${encodeURIComponent(streamSlug)}`;

    const res = await fetch(url);
    const json = await res.json();
    return Boolean(json?.success && json?.data?.available);
  }

  async function maybeMountOverlay() {
    const available = await shouldShowStreamOverlay(
      "your-org",
      "summer-campaign"
    );

    if (!available) {
      // Do not inject iframe / floating button
      return;
    }

    // Mount your overlay or iframe:
    // https://app.dailyplay.ai/stream/your-org/summer-campaign/widget?origin=...
  }

  maybeMountOverlay();
  // Optional: re-check every ~30s to match CDN cache
  setInterval(maybeMountOverlay, 30000);
</script>
```

### 检查通过后推荐的 stream URL

| 用途 | URL |
| ------- | --- |
| 完整 stream 页面 | `https://app.dailyplay.ai/stream/<org-slug>/<stream-slug>` |
| Widget / 悬浮浮层 | `https://app.dailyplay.ai/stream/<org-slug>/<stream-slug>/widget?origin=<encoded-site-origin>` |

托管 widget 代码片段见[悬浮游玩按钮](/zh/sharing/floating-play-button/)。DailyPlay 的 widget 脚本也会门控 stream 启动器，仅在 stream 可玩时显示。

:::note[Session tokens]
若 stream 需要 API session token，可用性仍可为 `true`，但游玩需要令牌。使用 [Session Tokens](/zh/api/session-tokens/) API（Business+）生成令牌。
:::

---

## 下一步

- [嵌入游戏与 streams](/zh/sharing/embed/)
- [悬浮游玩按钮](/zh/sharing/floating-play-button/)
- 用于受控访问的 [Session Tokens](/zh/api/session-tokens/)
- 完整端点列表见 [API Reference](/zh/api/reference/)