# 使用通配 Token (/zh-CN/realtime-media/rtc/build/security-and-auth/wildcard-token/android)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

用户在进行音视频互动时，声网会使用 Token 对用户鉴权。观众如果需要加入多个频道，或在频道间频繁切换，每加入一个新的频道都需要向服务端申请一个 Token，然后通过用户 ID (`uid`)、频道名 (`channelName`)、以及获取到的 Token 来加入频道。

为解决在切换频道时需要频繁申请 Token 的问题，声网提供将**用户 ID** 或**频道名**设为通配符的通配 Token。通过使用通配 Token，观众可以复用同一个 Token 加入不同频道，既可减少频繁获取 Token 所造成的耗时，从而加快切换、加入频道的速度，同时也能减小你的 Token 服务器的压力。

## 前提条件 [#前提条件]

在生成通配 Token 前，请确保你已部署 AccessToken2 服务器。详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。如果你使用的是 AccessToken，请参考 [AccessToken 升级指南](/zh-CN/realtime-media/rtc/build/setup-and-access/token-server-upgrade)升级至 AccessToken2。

## 生成通配 Token [#生成通配-token]

你可以通过 AccessToken2 的[生成器代码](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication#token-code)按需选用 `BuildTokenWithUid`[1/2] 或 `BuildTokenWithUid`[2/2]，并填入对应参数信息。

生成通配 Token 时，需要注意以下参数的填写：

| Token 类型   | uid                | channelName                                     |
| :------------ | :------------------------------- | :----------------------------------------------------------- |
| 通配用户 ID 的 Token | 将用户 ID (`uid`) 设为 0 或通配符 `*`（表示匹配任意长度的字符），可匹配 `int` 型及 `string` 型的用户 ID。声网还支持拓展匹配，即匹配多个 `*` 和字符串的组合，如 `1*a*2`（表示匹配以 1 开头、包含字母 a、以 2 结尾的用户 ID，如 1abc2）。 | 频道名，长度在 64 字节以内的字符串。|
| 通配频道名的 Token | 待鉴权用户的用户 ID ，支持使用 `int`、`string` 型的用户 ID。 | 将频道名设为通配符 `*` 或设为空，支持拓展匹配，即匹配多个 `*` 和字符串的组合，如 `1*a*2`（表示匹配以 1 开头、包含字母 a、以 2 结尾的频道名，如 1abc2）。 |

## 注意事项 [#注意事项]

- 如果你生成了 `uid` 为 `0` 的 Token，在使用时请注意：

   - 如果你只需要加入某**一个**频道，在调用 [`joinChannel`](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_joinchannel) 加入频道时，`uid` 可以设为 `0`。

   - 如果你需要加入**多个**频道，在调用 [`joinChannelEx`](/zh-CN/api-reference/rtc/android/channel#api_irtcengineex_joinchannelex) 加入频道时，请确保将 `uid` 设为具体的用户 ID 而非 `0`。

- 为避免 Token 泄露后非法用户扰乱频道内秩序、炸房捣乱，声网建议将使用通配 Token 的用户角色设为观众，用户权限 (`role`) 设为接收流 (`kRoleSubscriber`)。

   :::info[信息]
   在设置前请确保你已经开启连麦鉴权，详见[如何使用连麦鉴权功能](/zh-CN/reference/faq/integration/token_cohost#3-开启连麦鉴权)。
   :::

   如果使用通配 Token 的观众需要连麦，声网建议按照如下步骤来更新 Token（下列 API 以 C++ 为例）：

   1. 调用 [`setClientRole`](/zh-CN/api-reference/rtc/android/channel#setclientrole) 来将用户角色设为主播（`BROADCASTER`）。

   2. 生成 Token 时，在 `BuildTokenWithUid` 方法中指定频道名和用户 ID，且将用户权限（`role`）设为发流（ `kRolePublisher`），从而生成具有发流权限的 Token。

   3. 调用 [`renewToken`](/zh-CN/api-reference/rtc/android/channel#api_irtcengine_renewtoken) 来更新 Token。

- 通配 Token 的有效期为 24 小时，如果 Token 过期，你需要在服务端重新生成新的通配 Token，然后调用 `renewToken` 来传入新的通配 Token。

## 参考文档 [#参考文档]

- [使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)

- [AccessToken 升级指南](/zh-CN/realtime-media/rtc/build/setup-and-access/token-server-upgrade)

- [如何使用连麦鉴权功能？](/zh-CN/reference/faq/integration/token_cohost)