# 認証ウェブフック成功時の払い出し

## 概要

Sora では認証ウェブフック成功時に様々な値を外部の認証サーバーから払い出すことができます。

Sora は払い出された値を反映した状態でクライアントへの接続要求 `("type": "offer")` を送ります。

## audio の払い出し

クライアントが指定してきた音声のコーデックやビットレートなどのパラメータに対して、
認証サーバー側で新たに値を払い出すことで、上書きを行えます。

クライアントが指定してきた値を上書きすることができるため、
サーバー側でそれぞれのクライアントに対して、音声のコーデックやビットレートをコントロールすることができます。

### レガシーな払い出し例

> **重要**
>
> これは `sora.conf` にて [legacy_webhook_audio_video_json_structure](SORA_CONF.html#3be597) が `true` の場合の設定方法です。
> この設定は 2023 年 12 月リリース予定の Sora にて利用できなくなります。

この機能を使用する場合は、認証成功時のレスポンス JSON に `audio` を指定してください。
ここで使用できるのはシグナリングの `"type": "connect"` 時に指定可能な `audio` の値です。
ただしレガシーな払い出しの場合は `opus_params` や `lyra_params` は指定できません。

```json
{
    "allowed": true,
    "audio": {
        "codec_type": "OPUS",
        "bit_rate": 64
    }
}
```

#### 指定可能な値

- audio- `true` または `false` または object が指定可能です
- codec_type- "OPUS"
  - codec_type を指定しないことも可能です
- bit_rate- 6 ~ 510
  - 単位は kbps です
  - デフォルトで最適なビットレートが選択されるようになっているため指定する必要はありません

### フラットな払い出し例

これは `sora.conf` にて [legacy_webhook_audio_video_json_structure](SORA_CONF.html#3be597) が `false` の場合の設定方法です。

この機能を使用する場合は、認証成功時のレスポンス JSON に `audio` や `audio_codec_type` や `audio_bit_rate` を指定してください。
ここで使用できるのはシグナリングの `"type": "connect"` 時に指定可能な `audio` の値です。

```json
{
    "allowed": true,
    "audio": true,
    "audio_codec_type": "OPUS",
    "audio_bit_rate": 64
}
```

#### 指定可能な値

- audio- `true` または `false` または object が指定可能です
- audio_codec_type- "OPUS"
  - codec_type を指定しないことも可能です
- audio_bit_rate- 6 ~ 510
  - 単位は kbps です
  - **デフォルトで最適なビットレートが選択されるようになっているため指定する必要はありません**
- audio_opus_params- **この機能はフラット構造でのみ利用可能です**
  - [オーディオの Opus 設定指定](SIGNALING.html#c82100) をオブジェクトとして指定可能です
- audio_lyra_params- **この機能はフラット構造でのみ利用可能です**
  - [オーディオの Lyra 設定指定](SIGNALING.html#ba1209) をオブジェクトとして指定可能です

## video の払い出し

クライアントが指定してきた映像のコーデックやビットレートなどのパラメータに対して、
認証サーバー側で新たに値を払い出すことで、上書きを行えます。

クライアントが指定してきた値を上書きすることができるため、
サーバー側でそれぞれのクライアントに対して、映像のコーデックやビットレートを指定することができます。

### レガシーな払い出し例

> **重要**
>
> これは `sora.conf` にて [legacy_webhook_audio_video_json_structure](SORA_CONF.html#3be597) が `true` の場合の設定方法です。
> この設定は 2023 年 12 月リリース予定の Sora にて利用できなくなります。

この機能を使用する場合は、認証成功時のレスポンス JSON に `video` を指定してください。
ここで使用できるのはシグナリングの `"type": "connect"` 時に指定可能な `video` の値です。

```json
{
    "allowed": true,
    "video": {
        "codec_type": "VP9",
        "bit_rate": 1000
    }
}
```

#### 指定可能な値

- "video"- true または false または object が指定可能です
- "codec_type"- 文字列で指定可能です
  - "VP8"
  - "VP9"
  - "AV1"
  - "H264"
  - "H265"- `sora.conf` にて [h265](SORA_CONF.html#2e0d28) を `true` にしている必要があります
  - codec_type を指定しないことも可能です
- "bit_rate"- 1 ~ 30000- サポートされている値は 1 ~ 15000 までです
  - 単位は kbps です
  - bit_rate を指定しないことも可能です

### フラットな払い出し例

これは `sora.conf` にて [legacy_webhook_audio_video_json_structure](SORA_CONF.html#3be597) が `false` の場合の設定方法です。

この機能を使用する場合は、認証成功時のレスポンス JSON に `video` や `video_codec_type` や `video_bit_rate` を指定してください。
ここで使用できるのはシグナリングの `"type": "connect"` 時に指定可能な `video` の値です。

```json
{
    "allowed": true,
    "video": true,
    "video_codec_type": "VP9",
    "video_bit_rate": 1000
}
```

#### 指定可能な値

- "video"- true または false または object が指定可能です
- "video_codec_type"- 文字列で指定可能です
  - "VP8"
  - "VP9"
  - "AV1"
  - "H264"
  - "H265"- `sora.conf` にて [h265](SORA_CONF.html#2e0d28) を `true` にしている必要があります
  - codec_type を指定しないことも可能です
- "video_bit_rate"- 1 ~ 30000- サポートされている値は 1 ~ 15000 までです
  - 単位は kbps です
  - bit_rate を指定しないことも可能です

## client_id の払い出し

Sora は認証成功時の戻り値に `client_id` を認証サーバーから返すことができます。

シグナリング接続時にも、 認証成功時の戻り値にも `client_id` を指定しない場合は `connection_id` と同じ値が `client_id` に割りあてられます。

```json
{
    "allowed": true,
    "client_id": "spam"
}
```

- client_id- 1 から 255 の長さの文字列

## bundle_id の払い出し

Sora は認証成功時の戻り値に `bundle_id` を認証サーバーから返すことができます。

`bundle_id` を指定した場合、マルチストリーム利用時に `bundle_id` の値が同じ接続からの音声や映像、メッセージング、シグナリング通知を受信しなくなります。

シグナリング接続時にも、 認証成功時の戻り値にも `bundle_id` を指定しない場合は `connection_id` と同じ値が `bundle_id` に割りあてられます。

```json
{
    "allowed": true,
    "bundle_id": "spam"
}
```

- bundle_id- 1 から 255 バイトの文字列

## data_channel_signaling の払い出し

Sora は、認証成功時のタイミングで接続単位での `data_channel_signaling` の値を認証サーバーから払い出すことが可能です。

```json
{
    "allowed": true,
    "data_channel_signaling": true
}
```

この値は `"type": "connect"` の `data_channel_signaling` や `sora.conf` の [default_data_channel_signaling](SORA_CONF.html#adceef) の値を上書きします。

### 認証成功時にクライアントが受け取る JSON

```json
{
    "type": "offer",
    "sdp": "<SDP>",
    "data_channel_signaling": true,
    "ignore_disconnect_websocket": false
}
```

## ignore_disconnect_websocket の払い出し

Sora は、認証成功時のタイミングで接続単位での `ignore_disconnect_websocket` の値を認証サーバーから払い出すことが可能です。

```json
{
    "allowed": true,
    "ignore_disconnect_websocket": true
}
```

この値は `"type": "connect"` の `ignore_disconnect_websocket` や `sora.conf` の [default_ignore_disconnect_websocket](SORA_CONF.html#58fe04) の値を上書きします。

ただし `data_channel_signaling` が `true` の時のみ、この値は有効になります。

### 認証成功時にクライアントが受け取る JSON

data_channel_signaling が有効な場合、 `"type": "switched"` が送られる際に `ignore_disconnect_websocket` も送られます。

```json
{
    "type": "switched",
    "ignore_disconnect_websocket": "<bool>",
}
```

## data_channels の払い出し

Sora は、認証成功時のタイミングで接続単位での `data_channels` の値を認証サーバーから払い出すことができます。

```json
{
    "allowed": true,
    "data_channels": [
        {
            "label": "#spam",
            "max_packet_life_time": 5000,
            "ordered": true,
            "protocol": "efg",
            "compress": false,
            "direction": "sendonly"
        },
        {
            "label": "#egg",
            "max_retransmits": 0,
            "ordered": false,
            "protocol": "abc",
            "compress": false,
            "direction": "recvonly"
        }
    ]
}
```

`data_channels` の詳細仕様は [data_channels 仕様](MESSAGING.html#ad1989) をご確認ください。

## metadata の払い出し

Sora は、認証成功時のタイミングで `metadata` という値を認証サーバーから払い出すことができます。

```json
{
    "allowed": true,
    "metadata": {"spam": "egg"}
}
```

認証サーバーが認証成功時に `metadata` を含めた場合、クライアントへ送る `"type": "offer"` に `metadata` をそのまま送ります。

この機能を使うことで、認証成功のタイミングでユーザー毎に任意の値を送ることができます。

### 認証成功時にクライアントが受け取る JSON

認証成功の場合は Offer 送信時の JSON に `metadata` が含められます。

```json
{
    "type": "offer",
    "sdp": "<SDP>",
    "metadata": {"spam": "egg"}
}
```

## event_metadata の払い出し

**event_metadata はクライアントには送られません**

Sora は、認証成功時のタイミングで `event_metadata` という値を認証サーバーから払い出すことができます。

認証サーバーが認証成功時に `event_metadata` を含めた場合、
イベントウェブフックリクエスト送信時に `event_metadata` という項目が追加されます。

```json
{
    "allowed": true,
    "event_metadata": {"pk": 1}
}
```

`event_metadata` はクライアントに知られることのない値です。
Sora イベントウェブフックリクエスト送信先のサーバーのみが知り得る値となります。

### 使用例

この `event_metadata` の値は、クライアントに知られることはありません。そのためユーザー ID を直接入れておくという仕組みも使用できます。

こうすることで通知の際、サーバー側がユーザーの判定をしやすくなります。

## シグナリング経由での通知機能の払い出し

Sora は、認証成功時のタイミングで `signaling_notify` という値を認証サーバーから払い出すことができます。

```json
{
    "allowed": true,
    "signaling_notify": true
}
```

`signaling_notify` の値を返すことで、クライアント毎にシグナリング通知を受け取るかどうかを指定可能になります。

シグナリング経由での通知機能の詳細は ["type": "notify"](SIGNALING.html#c4828f) をご確認ください

### シグナリング経由での通知機能を利用したメタデータの払い出し

Sora は、認証成功時のタイミングで `signaling_notify_metadata` という値を認証サーバーから払い出すことができます。

ここに値を指定することで、参加時や離脱時に外の参加者に情報を通知することができます。

```json
{
    "allowed": true,
    "signaling_notify_metadata": {
        "username": "spam"
    }
}
```

詳細は [signaling_notify_metadata](SORA_CONF.html#2d9340) をご確認ください。

## ipv4_address と ipv6_address の払い出し

Sora は、認証成功時のタイミングで `ipv4_address` または `ipv6_address` を認証サーバーから払い出すことができます。
`ipv4_address` と `ipv6_address` は片方だけでも、両方返しても問題ありません。

```json
{
    "allowed": true,
    "ipv4_address": "192.0.2.10",
    "ipv6_address": "2001:0DB8::10"
}
```

この値は SDP の offer 時の a=candidate と TURN-UDP と TURN-TCP の URL の払い出しに使用されます。

`sora.conf` の値はこの戻り値で上書きされます。指定する IP アドレスを間違えると繋がらなくなるため、使用には注意してください。

この機能を使用することでクライアント毎に経路を指定することができます。

## turn_fqdn 払い出し

Sora は、認証成功時のタイミングで接続単位での `turn_fqdn` の値を認証サーバーから払い出すことができます。

```json
{
    "allowed": true,
    "turn_fqdn": "sora-turn.example.com"
}
```

この値は `sora.conf` の [turn_fqdn](SORA_CONF.html#6513e4) の値を上書きします。

指定する FQDN を間違えると繋がらなくなるため、使用には注意してください。

## turn_tls_fqdn の 払い出し

Sora は、認証成功時のタイミングで接続単位での `turn_tls_fqdn` の値を認証サーバーから払い出すことができます。

```json
{
    "allowed": true,
    "turn_tls_fqdn": "sora-turn.example.com"
}
```

この値は sora.conf の `turn_tls_fqdn` の値を上書きします。指定する FQDN を間違えると繋がらなくなるため、使用には注意してください。

この機能は `sora.conf` の [turn_tls_fqdn](SORA_CONF.html#3bfd30) の値を上書きします。

## turn_tcp_only / turn_tls_only の払い出し

Sora は、認証成功時のタイミングで接続単位での `turn_tcp_only` または `turn_tls_only` の値を認証サーバーから払い出すことができます。

```json
{
    "allowed": true,
    "turn_tcp_only": true
}
```

```json
{
    "allowed": true,
    "turn_tls_only": true
}
```

この値は `sora.conf` の [turn_tcp_only](SORA_CONF.html#479c51) や [turn_tls_only](SORA_CONF.html#58d702) の値を上書きします。

## simulcast / simulcast_rid の払い出し

Sora は、認証成功時のタイミングで接続単位での `simulcast` と `simulcast_rid` の値を認証サーバーから払い出すことが可能です。

```json
{
    "allowed": true,
    "simulcast": true
}
```

```json
{
    "allowed": true,
    "simulcast": true,
    "simulcast_rid": "r0"
}
```

この値は `sora.conf` の `default_simulcast_rid` の値を上書きします。

## simulcast_encodings の払い出し

Sora は、認証成功時のタイミングで接続単位での `simulcast_encodings` の値を認証サーバーから払い出すことが可能です。

```json
{
    "allowed": true,
    "simulcast_encodings": [
        {"rid": "r0", "active": true, "scaleResolutionDownBy": 2.0, "maxFramerate": 1.0},
        {"rid": "r1", "active": true, "scaleResolutionDownBy": 2.0, "maxFramerate": 10.0},
        {"rid": "r2", "active": true, "scaleResolutionDownBy": 1.0, "maxFramerate": 30.0}
    ]
}
```

詳細については [サイマルキャスト](SIMULCAST.html) の [映像のエンコーディングパラメータのカスタマイズ](SIMULCAST.html#03a03b) をご確認ください。

## spotlight_encodings の払い出し

Sora は、認証成功時のタイミングで接続単位での `spotlight_encodings` の値を認証サーバーから払い出すことが可能です。

```json
{
    "allowed": true,
    "spotlight_encodings": [
        {"rid": "r0", "active": true, "scaleResolutionDownBy": 4.0, "maxFramerate": 1.0},
        {"rid": "r1", "active": true, "scaleResolutionDownBy": 1.0, "maxFramerate": 10.0},
        {"rid": "r2", "active": false}
    ]
}
```

詳細については [サイマルキャスト](SIMULCAST.html) の [映像のエンコーディングパラメータのカスタマイズ](SIMULCAST.html#03a03b) をご確認ください。

## spotlight / spotlight_number の払い出し

Sora は、認証成功時のタイミングで接続単位での `spotlight` と `spotlight_number` の値を認証サーバーから払い出すことが可能です。

```json
{
    "allowed": true,
    "spotlight": true
}
```

```json
{
    "allowed": true,
    "spotlight": true,
    "spotlight_number": 3
}
```

## user_agent_stats の払い出し

Sora は、認証成功時のタイミングで接続単位での `user_agent_stats` の値を認証サーバーから払い出すことが可能です。

```json
{
    "allowed": true,
    "user_agent_stats": true
}
```

この値は `sora.conf` の [user_agent_stats](SORA_CONF.html#b8b6ef) の値を上書きします。

## h264_profile_level_id の払い出し

Sora は、認証成功時のタイミングで接続単位での `h264_profile_level_id` の値を認証サーバーから払い出すことが可能です。

```json
{
    "allowed": true,
    "h264_profile_level_id": "42e01f"
}
```

この値は `sora.conf` の [default_h264_profile_level_id](SORA_CONF.html#8a25f5) の値を上書きします。

## audio_streaming_language_code の払い出し

Sora は、認証成功時のタイミングで音声ストリーミングのランゲージコードの値を認証サーバーから払い出すことが可能です。

```json
{
    "allowed": true,
    "audio_streaming_language_code": "ja-JP"
}
```

この値は接続時の `audio_streaming_language_code` と `sora.conf` の [default_audio_streaming_language_code](SORA_CONF.html#856531) の値を上書きします。