> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 通知声音

> 为 iOS、Android、Huawei 和 Amazon 应用添加自定义通知声音——包括文件格式、SDK 设置和 API 参数。

自定义声音让您的应用提供更独特、品牌化的体验。您可以为发送的每个通知添加自定义声音，或只为某些类型的通知添加声音。例如，社交应用可能只为私信播放独特声音，以区别于系统通知。

<Warning>
  仅适用于移动应用。网页推送不支持自定义声音。
</Warning>

## 设置

### 创建声音文件

按照以下平台要求创建声音文件。如果设备找不到指定文件或文件格式不受支持，将回退到默认系统通知声音。

<Note>
  保持声音文件名小写，因为某些平台忽略声音文件的大写字母。使用 `awesomesound.wav` 或 `awesome_sound.wav` 而不是 `AwesomeSound.wav`。
</Note>

| 平台      | 扩展名                   | 注释                                                        |
| ------- | --------------------- | --------------------------------------------------------- |
| iOS     | `.wav` `.aiff` `.caf` | 声音必须编码为 Linear PCM、MA4 (IMA/ADPCM)、µLaw 或 aLaw。必须少于 30 秒。 |
| Android | `.wav` `.mp3` `.ogg`  | 建议长度少于 30 秒。保持文件大小较小，大文件可能在某些设备上无法播放。                     |
| Huawei  | `.wav` `.mp3` `.wma`  | 建议长度少于 30 秒。保持文件大小较小，大文件可能在某些设备上无法播放。                     |
| Amazon  | `.wav` `.mp3` `.ogg`  | 建议长度少于 30 秒。保持文件大小较小，大文件可能在某些设备上无法播放。                     |

### 将声音文件添加到您的应用

声音文件必须作为资源包含在应用程序中。不支持外部 URL。

<Tabs>
  <Tab title="iOS">
    根据您的 SDK，将声音文件添加到 Xcode 项目中的适当位置。

    | SDK            | Folder                                                                                     |
    | -------------- | ------------------------------------------------------------------------------------------ |
    | iOS Native     | 将文件添加到 Xcode 项目根目录。添加文件时请确保选择 **Add to targets**，以便它们自动添加到包资源中。                            |
    | Cordova, Ionic | 将文件添加到 Xcode 项目中的 `Resources` 目录，位于 `<project-root>/platforms/ios/project-name.xcodeproj`。 |
    | Unity          | 在 Unity 项目中的任何位置添加声音文件，构建项目，然后将这些声音文件移动到 Xcode 项目根目录。                                      |
  </Tab>

  <Tab title="Android、Huawei 和 Amazon">
    根据您的 SDK 将声音文件添加到项目中的适当文件夹。**如果文件夹不存在，请创建它。**

    | SDK                            | Folder                                                                                    |
    | ------------------------------ | ----------------------------------------------------------------------------------------- |
    | Android, Huawei, Amazon Native | `res/raw`                                                                                 |
    | React Native                   | `<project-root>/android/app/src/main/res/raw`                                             |
    | Cordova                        | `<project-root>/platforms/android/res/raw/`                                               |
    | Ionic                          | `/android/app/src/main/res/raw/`                                                          |
    | Unity                          | `Assets/Plugins/Android/OneSignalConfig/res/raw` *注意：您的声音和图标文件名必须小写，且不能包含除下划线和数字以外的其他字符。* |
    | Flutter                        | `main/res/raw`                                                                            |
    | .NET                           | `<project-root>/Platforms/Android/Resources/raw/`                                         |
  </Tab>
</Tabs>

### 发送通知

<Tabs>
  <Tab title="iOS">
    引用声音资源时请包含文件扩展名（例如 `explode_sound.wav`）。在发送推送消息时在仪表板中设置声音，或使用[创建通知](/reference/create-message) API 的 `ios_sound` 属性。

    如需无声音，请在 **声音** 字段中传入 `nil`。

    <Frame caption="在 OneSignal 仪表板中为 iOS 设置自定义声音。">
      <img src="https://mintcdn.com/onesignal/6tscVAtiSqz353kV/images/docs/a05af7e-Screenshot_2023-02-28_at_3.16.55_PM.png?fit=max&auto=format&n=6tscVAtiSqz353kV&q=85&s=9d33c9837ac9f67b0d6c6a7a87d03212" alt="OneSignal dashboard push composer showing the iOS Sound field" width="423" height="606" data-path="images/docs/a05af7e-Screenshot_2023-02-28_at_3.16.55_PM.png" />
    </Frame>
  </Tab>

  <Tab title="Android、Huawei 和 Amazon">
    Android 8+ 引入了[通知类别](./android-notification-categories)，必须设置才能自定义通知声音。OneSignal 使用通知渠道中配置的声音，适用于所有 Android 版本。

    在 **设置 > 推送和应用内 > Android 通知渠道**，创建组和渠道。

    <Frame caption="创建通知渠道。">
      <img src="https://mintcdn.com/onesignal/tc0EvmtSSX56SX0c/images/docs/8f39237-Screenshot_2023-02-28_at_3.11.52_PM.png?fit=max&auto=format&n=tc0EvmtSSX56SX0c&q=85&s=b18a97c1706dde194bd4e5c13cd9f593" alt="OneSignal dashboard showing the notification channel creation form" width="877" height="487" data-path="images/docs/8f39237-Screenshot_2023-02-28_at_3.11.52_PM.png" />
    </Frame>

    * 将 **重要性** 设置为"紧急"或"高"以播放声音。
    * 根据您的需要将 **声音** 设置为"默认"或"自定义"。引用声音资源时 **请勿** 添加文件扩展名（例如 `cat_meow_sound`）。
    * 对于无声音，将 **重要性** 设置为"紧急"或"高"，并将 **声音** 设置为"关闭"。或将 **重要性** 设置为"中等"或"低"以实现无声音。

    <Frame caption="为通知渠道设置声音。">
      <img src="https://mintcdn.com/onesignal/KSCNwSpBCNSQ8xdF/images/docs/f7950b6-Screenshot_2023-02-28_at_3.11.03_PM.png?fit=max&auto=format&n=KSCNwSpBCNSQ8xdF&q=85&s=88d88df41d360b190b4c083709e8119c" alt="OneSignal notification channel settings showing sound configuration options" width="429" height="498" data-path="images/docs/f7950b6-Screenshot_2023-02-28_at_3.11.03_PM.png" />
    </Frame>

    然后，您可以在发送推送消息时在仪表板中设置类别名称，或使用[创建通知](/reference/create-message) API 的 `android_channel_id` 和 `huawei_channel_id` 属性。类别中设置的声音适用于所有 Android 版本。

    <Frame caption="在推送消息编辑器中选择通知类别。">
      <img src="https://mintcdn.com/onesignal/jFWn5xzleD8du3j6/images/docs/5e8625c-Screenshot_2023-02-28_at_3.15.19_PM.png?fit=max&auto=format&n=jFWn5xzleD8du3j6&q=85&s=c02f9a68fcb73b913a1de93e01d0f4aa" alt="OneSignal push composer showing the notification category dropdown" width="423" height="517" data-path="images/docs/5e8625c-Screenshot_2023-02-28_at_3.15.19_PM.png" />
    </Frame>
  </Tab>

  <Tab title="REST API">
    您可以通过 REST API 使用各平台对应的参数发送带声音的通知。详情请参阅[创建通知 API 参考](/reference/push-notification)。

    | Platform | API Parameter                                                                                                                                        | Details                                                       |
    | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
    | iOS      | `ios_sound`                                                                                                                                          | 包含文件扩展名。示例：`"ios_sound": "explode_sound.wav"`。如需无声音，传入 `nil`。 |
    | Android  | `android_channel_id` — 如果您在 OneSignal 仪表板通过[通知类别](./android-notification-categories)创建了渠道，请使用此参数。`existing_android_channel_id` — 如果您在别处创建了渠道，请使用此参数。 | 建议使用[通知类别](./android-notification-categories)。                |
    | Huawei   | `huawei_channel_id` — 如果您在 OneSignal 仪表板通过[通知类别](./android-notification-categories)创建了渠道，请使用此参数。`huawei_existing_channel_id` — 如果您在别处创建了渠道，请使用此参数。   | 建议使用[通知类别](./android-notification-categories)。                |
    | Amazon   | `adm_sound`                                                                                                                                          | 不包含文件扩展名。示例：`"adm_sound": "explode_sound"`。                   |
  </Tab>
</Tabs>

<Warning>
  如果您最近向应用添加了声音资源，请考虑等待几天后再发送使用该声音的通知。大多数用户更新到包含新声音文件的最新版本可能需要数天或数周时间。

  如果用户使用的是不包含声音资源的旧版本应用，并收到引用该声音的通知，他们将只听到默认的系统通知声音。
</Warning>

***

## 常见问题

### 我可以设置默认声音吗？

使用引用声音和/或 Android 通知渠道的[模板](./templates)。使用该模板发送的每条通知都会自动使用已配置的声音。

### 我可以向不同用户发送不同的通知声音吗？

`ios_sound` 和 `android_channel_id` 参数是请求级别的——它们适用于该 API 调用的**所有**接收者。您无法在单个请求中为不同用户指定不同的声音。

要向不同用户发送不同声音，请使用**扇出模式**：为每个声音变体单独发出 API 调用，通过标签或分段定向用户。例如，将每个用户的首选声音存储在 `preferred_sound` 等[标签](./add-user-data-tags)中，然后每个声音值发送一个请求。

<CodeGroup>
  ```json Request 1 — "chime" users theme={null}
  {
    "app_id": "YOUR_APP_ID",
    "contents": {"en": "You have a new message!"},
    "ios_sound": "chime.wav",
    "android_channel_id": "CHIME_CHANNEL_ID",
    "include_filters": [
      {"field": "tag", "key": "preferred_sound", "relation": "=", "value": "chime"}
    ]
  }
  ```

  ```json Request 2 — "bell" users theme={null}
  {
    "app_id": "YOUR_APP_ID",
    "contents": {"en": "You have a new message!"},
    "ios_sound": "bell.wav",
    "android_channel_id": "BELL_CHANNEL_ID",
    "include_filters": [
      {"field": "tag", "key": "preferred_sound", "relation": "=", "value": "bell"}
    ]
  }
  ```
</CodeGroup>

每个请求只定向 `preferred_sound` 标签匹配的用户，因此每组用户听到各自的声音。根据需要添加任意数量的变体——每种声音一个 API 调用。

### 为什么我的通知没有播放自定义声音文件？

常见原因如下：

* 声音文件扩展名不正确
* 声音文件未以支持的格式编码
* 声音文件在项目中的位置错误
* 声音文件超过 30 秒

**iOS** — 请参阅 [Apple 的文档](https://developer.apple.com/documentation/usernotifications/unnotificationsound?language=objc)获取编码和测试指南。

**Android** — 通过提取 APK 并确认声音文件存在于 `res/raw/` 中来验证其是否已包含在 APK 中。

如果启用了资源压缩，请在 `res/raw/` 中创建 `keep.xml` 来保护声音文件不被删除：

```xml theme={null}
<resources xmlns:tools="http://schemas.android.com/tools"
  tools:keep="@raw/sound_file"/>
```

### 为什么我的通知播放的是默认声音文件？

请确保您遵循了设置说明，并且声音文件位于 SDK 的正确位置。仔细检查文件名大小写——某些平台忽略大写字母。

### 为什么播放的是错误的声音？

在 Android 上，当收到一定数量的通知未打开时，通知会被分组在一起。分组通知播放默认声音。您可以使用[分组键](https://developer.android.com/training/notify-user/group)为所有通知设置声音。

***

## 相关页面

<Columns cols={2}>
  <Card title="通知类别" icon="layer-group" href="./android-notification-categories">
    设置 Android 通知渠道以控制声音、振动和重要性。
  </Card>

  <Card title="模板" icon="file-lines" href="./templates">
    创建带有预定义声音的可重用通知模板。
  </Card>

  <Card title="创建通知 API" icon="code" href="/reference/push-notification">
    ios\_sound、android\_channel\_id 和 adm\_sound 参数的 API 参考。
  </Card>

  <Card title="通知图标" icon="image" href="./notification-icons">
    为您的移动应用自定义通知图标。
  </Card>
</Columns>