# ストリームステータスAPI

**ストリームステータス**エンドポイントで、ストリームを今すぐ表示すべきかをDailyPlayに問い合わせできます —
サイトにiframe、フローティングPlayボタン、またはカスタムオーバーレイを載せる前に使います。

これは**公開GET**（APIキー不要）です。次のようなサイト／アプリ運営者向けです：

- ストリームが**アクティブなときだけ**オーバーレイを表示する
- キャンペーン開始前・終了後はPlayボタンを隠す
- 公開済みゲームがないときにフルプレイヤーを読み込まない

:::tip[軽量設計]
フルのストリームプレイヤー用ペイロードと違い、このエンドポイントはゲーム設定や賞品を返さず、
分析も記録しません。可用性のゲートにはこちらを使い、`available` が `true` のときだけストリームURLを読み込んでください。
:::

## エンドポイント

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

| パラメータ     | 必須 | 説明 |
| ------------- | ---- | ---- |
| `org_slug`    | はい | 組織スラッグ（ストリーム共有URLから） |
| `stream_slug` | はい | ストリームスラッグ（ストリーム共有URLから） |

**認証:** なし  
**CORS:** `Access-Control-Allow-Origin: *`（ブラウザから呼び出し可能）  
**キャッシュ:** `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` はリクエスト処理成功を意味します。ストリームUIを出すかは
**`data.available`** で判断してください。

### 利用可能

```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 | 訪問者がストリームをプレイできるとき `true` |
| `reason` | string \| null | 利用不可の理由（利用可能なときは `null`） |
| `total_games` | number | ストリーム上の**公開済み**ゲーム数（非公開時は `0`） |
| `starts_at` / `ends_at` | string \| null | スケジュール境界（ストリームタイムゾーンからISO UTC） |
| `timezone` | string | スケジュール判定に使うストリームタイムゾーン |
| `server_time` | string | 判定時点のサーバー時刻（ISO UTC） |
| `stream.slug` / `status` | string | ストリーム識別子とステータス |
| `organization.slug` | string | 組織スラッグ |

### 利用不可の理由

| `reason` | 意味 |
| -------- | ---- |
| `not_public` | ストリームが公開されていない（詳細は漏洩しない） |
| `stream_inactive` | ステータスが `active` でない（下書き／アーカイブなど） |
| `stream_not_started` | 現在時刻が `starts_at` より前 |
| `stream_ended` | 現在時刻が `ends_at` より後 |
| `no_games` | 公開・アクティブだが公開済みゲームがない |

### エラーレスポンス

| コード | とき |
| ------ | ---- |
| `400` | `org_slug` または `stream_slug` 欠落 |
| `404` | 組織またはストリームが見つからない |
| `405` | `GET` / `OPTIONS` 以外 |
| `500` | サーバーエラー |

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

---

## いつ「利用可能」になるか

次のすべてが真である必要があります：

1. 指定の組織スラッグ配下にストリームが存在する
2. ストリームが**公開**
3. ステータスが**`active`**
4. 開始時刻がある場合、すでに開始している（ストリームタイムゾーン）
5. 終了時刻がある場合、まだ終了していない
6. **公開済み**ゲームが1つ以上紐づいている

---

## 典型的な連携：オーバーレイをゲートする

フローティングPlayボタンやモーダルを、ストリームがライブになるまで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) {
      // iframe / フローティングボタンを挿入しない
      return;
    }

    // オーバーレイまたはiframeをマウント:
    // https://app.dailyplay.ai/stream/your-org/summer-campaign/widget?origin=...
  }

  maybeMountOverlay();
  // 任意: CDNキャッシュに合わせて約30秒ごとに再確認
  setInterval(maybeMountOverlay, 30000);
</script>
```

### 利用可能確認後のおすすめURL

| 用途 | URL |
| ---- | --- |
| フルストリームページ | `https://app.dailyplay.ai/stream/<org-slug>/<stream-slug>` |
| ウィジェット / フローティングオーバーレイ | `https://app.dailyplay.ai/stream/<org-slug>/<stream-slug>/widget?origin=<encoded-site-origin>` |

ホスト済みウィジェットスニペットは[フローティングPlayボタン](/ja/sharing/floating-play-button/)を参照。DailyPlayのウィジェットスクリプトも、プレイ可能なときだけストリームランチャーを表示するようゲートします。

:::note[セッショントークン]
ストリームがAPIセッショントークン必須でも、可用性は `true` のままプレイにトークンが必要な場合があります。トークン発行は[セッショントークン](/ja/api/session-tokens/)API（Business+）を使います。
:::

---

## 次のステップ

- [ゲームとストリームの埋め込み](/ja/sharing/embed/)
- [フローティングPlayボタン](/ja/sharing/floating-play-button/)
- 制御付きアクセスの[セッショントークン](/ja/api/session-tokens/)
- 全エンドポイント一覧の[APIリファレンス](/ja/api/reference/)