通知图标

设置推送通知图标，让用户能够在通知栏和锁屏上识别您的应用。Android、iOS 和 Web 各自使用不同的图标来源。如需了解附加到通知的大图像，请参阅图像和富媒体。

带有小徽章图标、大图标和图像的推送通知 — Android Chrome Web 推送通知示例，包含小徽章图标、大图标和图像。

Android 通知图标

Android（包括 Amazon 和 Huawei 设备）支持小和大通知图标。在 Android 8.0+（API 26+）上，通知类别和制造商 UI 也会影响通知的外观。 Android 还支持对话通知，它可以在您的图标位置显示某个人的个人资料图像。

小通知图标

小通知图标是必需的。它以单色剪影的形式显示在状态栏中。如果您不提供自定义小图标，OneSignal 将使用默认的铃铛图标。图标在通知上的位置在 Android 17（API 37）中发生了变化。请参阅通知上的启动器图标。 Android 使用图标的 alpha 通道而不是其颜色数据来呈现小通知图标。从 Android 12（API 31）开始，系统会使用您设置的通知强调色为该剪影着色。如果您不设置颜色，则使用系统主题颜色。请参阅 Android 通知设计。 要求：

在透明背景上使用单色剪影图标
设计图标时使形状由透明度定义，而不是颜色
避免渐变、阴影或多色艺术作品
保持设计简单且在非常小的尺寸下可识别

一种常见的方法是透明背景上的白色艺术作品。Android 使用的是 alpha 掩码，而不是白色本身。

具有实心背景或全彩艺术作品的图标通常会呈现为白色方块、裁剪形状或意外的剪影。Android 会忽略小通知图标中的颜色，并根据 alpha 通道加上系统或应用的着色来派生外观。

在原生 Android 上，您无法强制显示全彩小图标。在 Android 12（API 31）及更新版本上，自定义通知布局仍然显示由系统着色的小图标。某些制造商会忽略 alpha 通道并显示全彩图像。请不要依赖这种行为。请始终提供符合规则的 alpha 通道图标。

通知上的启动器图标（Android 17）

从 Android 17（API 37）开始，Android 在通知上显示应用的启动器图标而不是小图标。小图标仍会显示在状态栏中。这是适用于所有通知的 Android 系统行为，具体外观可能因设备制造商而异。要改为在通知上显示小图标，请设置 Android 的 EXTRA_PREFER_SMALL_ICON extra。OneSignal SDK 默认不设置此 extra。请在您的通知服务扩展中添加它。按照该页面所示，使用 @Keep 注解该类并在清单中注册它。

import android.os.Bundle
import androidx.annotation.Keep
import com.onesignal.notifications.INotificationReceivedEvent
import com.onesignal.notifications.INotificationServiceExtension

@Keep
class NotificationServiceExtension : INotificationServiceExtension {
    override fun onNotificationReceived(event: INotificationReceivedEvent) {
        event.notification.setExtender { builder ->
            // "android.app.preferSmallIcon" is Notification.EXTRA_PREFER_SMALL_ICON (API 37)
            builder.addExtras(Bundle().apply { putBoolean("android.app.preferSmallIcon", true) })
        }
    }
}

import android.os.Bundle;
import androidx.annotation.Keep;
import com.onesignal.notifications.INotificationReceivedEvent;
import com.onesignal.notifications.INotificationServiceExtension;

@Keep
public class NotificationServiceExtension implements INotificationServiceExtension {
    @Override
    public void onNotificationReceived(INotificationReceivedEvent event) {
        event.getNotification().setExtender(builder -> {
            Bundle extras = new Bundle();
            // "android.app.preferSmallIcon" is Notification.EXTRA_PREFER_SMALL_ICON (API 37)
            extras.putBoolean("android.app.preferSmallIcon", true);
            return builder.addExtras(extras);
        });
    }
}

该字符串键适用于任何 compileSdk 版本。Android 16（API 36）及以下版本会忽略此 extra，因此无条件设置是安全的。

小图标强调色

您可以设置 Android 12（API 31）及更新版本用于为小图标着色的通知强调色。这对应 Android 的 Notification.color（setColor）。它与为通知背景着色（setColorized）不同，后者是 Android 为高优先级持续任务保留的。强调色是按通知的属性，而不是渠道属性。Android 通知类别控制声音、重要性、振动、LED 颜色和徽章。类别没有强调色设置，无论通知显示在哪个类别上，您的强调色都会生效。

在 Android 17（API 37）及更新版本上，当显示启动器图标时，强调色可能不会显示在通知上。状态栏中的小图标仍会被着色。

Android notification showing small icon accent color

SDK 按以下顺序解析强调色。找到的第一个值生效：

按消息：创建消息 API 中的 android_accent_color（Google Android）或 huawei_accent_color（Huawei）参数，或 Messages > Push > New Push > Platform Settings > Google Android Options 下的 Accent color 字段。
通过资源设置应用默认值：onesignal_notification_accent_color 字符串资源。
通过清单设置应用默认值：AndroidManifest.xml 中的 com.onesignal.NotificationAccentColor.DEFAULT meta-data 条目。

使用不带 # 的 ARGB 十六进制值（例如 FF00FF00）。您可以在 Android Asset Studio 中预览颜色。要通过资源设置默认颜色，请将以下行添加到您的 res/values/strings.xml 文件中。如需在深色模式下使用不同的颜色，请将相同的键添加到 res/values-night/strings.xml。

<resources>
    <string name="onesignal_notification_accent_color">FF00FF00</string>
</resources>

要改为在清单中设置默认值，请在 <application> 标签内添加以下内容：

<meta-data android:name="com.onesignal.NotificationAccentColor.DEFAULT" android:value="FF00FF00" />

如需在显示时进行完全控制，请从通知服务扩展中使用带有 builder.setColor() 的 notification.setExtender 设置颜色。extender 在 SDK 应用上述值之后运行，因此它会覆盖所有这些值。

大通知图标

大图标是可选的。它显示在通知的右侧。Android 的设计指南是仅在图像强化通知内容时才使用它，例如发送者照片、第三方来源的徽标或有意义的符号。请不要将大图标用作第二个应用图标或用于品牌宣传。请参阅大图标。

推荐尺寸：256×256 像素
格式：PNG 或 JPG
允许颜色。不要求仅 alpha。

如果您不设置大图标，在原生 Android 上该位置将保持空白。某些制造商会改为显示应用启动器图标。

如何添加 Android 默认图标

为每个基于 Android 的应用（Google Play、Amazon、Huawei）配置默认图标。请先完成 Android SDK 设置（或您的跨平台设置）。将文件添加到项目的资源目录（或 Expo 的插件配置）中，重新构建并发布。缺失或命名不正确的文件是呈现损坏的最常见原因。默认图标捆绑在应用二进制文件中。它们不会上传到 OneSignal 仪表板。发布后，请等到大多数用户完成更新后，再发送依赖新图标名称的通知。

生成小通知图标

使用 Android Asset Studio – 通知图标生成透明背景上的剪影。请遵循小图标要求。图标名称： ic_stat_onesignal_default

创建所需的小图标尺寸

包含小图标的所有密度变体。缺少任何尺寸都可能导致 Android 回退到系统默认图标。这些尺寸在每个密度下均为 24dp，这是 Android 的状态栏图标尺寸。

图标名称	密度	尺寸 (px)
`ic_stat_onesignal_default`	MDPI	24×24
`ic_stat_onesignal_default`	HDPI	36×36
`ic_stat_onesignal_default`	XHDPI	48×48
`ic_stat_onesignal_default`	XXHDPI	72×72
`ic_stat_onesignal_default`	XXXHDPI	96×96

生成大通知图标（可选）

使用 256×256 的 PNG 或 JPG。允许颜色。只需要一个尺寸。所需文件名： ic_onesignal_large_icon_default.png

将图标放置在正确的项目路径中

创建任何缺失的文件夹。将每个密度的小图标放入其对应的 drawable 文件夹。将大图标放在 drawable-xxxhdpi/ 中，与 XXXHDPI 小图标放在一起。这两个文件共用一个文件夹并使用不同的名称。

小图标（ic_stat_onesignal_default）：

res/drawable-mdpi/ (24×24)
res/drawable-hdpi/ (36×36)
res/drawable-xhdpi/ (48×48)
res/drawable-xxhdpi/ (72×72)
res/drawable-xxxhdpi/ (96×96)

大图标（ic_onesignal_large_icon_default.png，256×256）：

res/drawable-xxxhdpi/

小图标（ic_stat_onesignal_default）：

Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res/drawable-mdpi/ (24×24)
Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res/drawable-hdpi/ (36×36)
Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res/drawable-xhdpi/ (48×48)
Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res/drawable-xxhdpi/ (72×72)
Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res/drawable-xxxhdpi/ (96×96)

大图标（ic_onesignal_large_icon_default.png，256×256）：

Assets/Plugins/Android/OneSignalConfig.androidlib/src/main/res/drawable-xxxhdpi/

使用小写文件名。允许使用下划线。

小图标（ic_stat_onesignal_default）：

android/app/src/main/res/drawable-mdpi/ (24×24)
android/app/src/main/res/drawable-hdpi/ (36×36)
android/app/src/main/res/drawable-xhdpi/ (48×48)
android/app/src/main/res/drawable-xxhdpi/ (72×72)
android/app/src/main/res/drawable-xxxhdpi/ (96×96)

大图标（ic_onesignal_large_icon_default.png，256×256）：

android/app/src/main/res/drawable-xxxhdpi/

Expo 快捷方式： 如果您使用 onesignal-expo-plugin，请提供一个 96×96 的小图标 PNG 和一个 256×256 的大图标 PNG。插件会生成所有密度变体。将它们添加到 app.json 或 app.config.js：

{
  "plugins": [
    ["onesignal-expo-plugin", {
      "mode": "production",
      "smallIcons": ["./assets/ic_stat_onesignal_default.png"],
      "largeIcons": ["./assets/ic_onesignal_large_icon_default.png"]
    }]
  ]
}

您无需自行创建 android/ drawable 文件夹。插件会在构建时放置生成的文件。有关完整的插件配置，请参阅 React Native / Expo SDK 设置。

小图标（ic_stat_onesignal_default）：

android/app/src/main/res/drawable-mdpi/ (24×24)
android/app/src/main/res/drawable-hdpi/ (36×36)
android/app/src/main/res/drawable-xhdpi/ (48×48)
android/app/src/main/res/drawable-xxhdpi/ (72×72)
android/app/src/main/res/drawable-xxxhdpi/ (96×96)

大图标（ic_onesignal_large_icon_default.png，256×256）：

android/app/src/main/res/drawable-xxxhdpi/

适用于仍在使用 Cordova 插件的 Ionic 应用。Capacitor 应用请使用 Capacitor 选项卡。小图标（ic_stat_onesignal_default）：

<project-root>/platforms/android/app/src/main/res/drawable-mdpi/ (24×24)
<project-root>/platforms/android/app/src/main/res/drawable-hdpi/ (36×36)
<project-root>/platforms/android/app/src/main/res/drawable-xhdpi/ (48×48)
<project-root>/platforms/android/app/src/main/res/drawable-xxhdpi/ (72×72)
<project-root>/platforms/android/app/src/main/res/drawable-xxxhdpi/ (96×96)

大图标（ic_onesignal_large_icon_default.png，256×256）：

<project-root>/platforms/android/app/src/main/res/drawable-xxxhdpi/

在 Cordova 7.0 之前的版本中，将图标资源添加到 config.xml 时，请改用 <project-root>/platforms/android/res/drawable-{size}/。

适用于 Capacitor 和 Ionic Capacitor 应用。请参阅 Capacitor SDK 设置。小图标（ic_stat_onesignal_default）：

android/app/src/main/res/drawable-mdpi/ (24×24)
android/app/src/main/res/drawable-hdpi/ (36×36)
android/app/src/main/res/drawable-xhdpi/ (48×48)
android/app/src/main/res/drawable-xxhdpi/ (72×72)
android/app/src/main/res/drawable-xxxhdpi/ (96×96)

大图标（ic_onesignal_large_icon_default.png，256×256）：

android/app/src/main/res/drawable-xxxhdpi/

小图标（ic_stat_onesignal_default）：

Platforms/Android/Resources/drawable-mdpi/ (24×24)
Platforms/Android/Resources/drawable-hdpi/ (36×36)
Platforms/Android/Resources/drawable-xhdpi/ (48×48)
Platforms/Android/Resources/drawable-xxhdpi/ (72×72)
Platforms/Android/Resources/drawable-xxxhdpi/ (96×96)

大图标（ic_onesignal_large_icon_default.png，256×256）：

Platforms/Android/Resources/drawable-xxxhdpi/

您的项目应类似于此（取决于您的 SDK）：

Android project directory structure showing icon files in drawable folders — Android Native 项目中 drawable 文件夹内的图标文件

您的 Android 应用现在已配置默认通知图标。如果您看到实心方块或 OneSignal 铃铛，请参阅常见问题。

iOS 通知图标

iOS 通知始终使用您的应用图标。系统在每条通知的前缘显示该图标的大尺寸版本，并从您的应用图标资源缩放而来。您无法按消息更改它。要更改它，请更新应用图标并发布新的应用版本。请参阅人机界面指南：通知。

APNs 负载包含 alert、badge 和 sound。它没有用于自定义通知图标的字段。Apple 会忽略 aps 字典内的自定义键。这适用于标准推送通知和关键警报。Live Activity UI 可以通过 ActivityKit 显示自己的图像。这不能替代通知图标。

通信通知

在 iOS 15 及更新版本上，Apple 为消息和通话应用支持通信通知。在您提供 INSendMessageIntent 或 INStartCallIntent 之后，系统可以在大应用图标的位置显示发送者或来电者的头像（INImage）。应用图标仍会作为小徽章显示在该头像上。这需要通信通知功能、SiriKit intents 以及用于更新通知内容的通知服务扩展。它不适用于通用通知。

Web 通知图标

Web 推送通知显示在发送时提供的图标或在您的网站设置中设置为默认的图标。如果未提供图标，则使用默认的铃铛图标。

支持的格式：PNG、JPG、GIF（非动画）
图标必须是正方形。推荐尺寸为 256×256 像素。web.dev 引用 Android 上的 64dp，因此 192×192 或更大是通常的最小尺寸。256×256 在 Chrome、Firefox、Edge 和 Safari 之间保持最一致的尺寸。
浏览器和操作系统裁剪和缩放图标的方式不同。Chrome 和 Firefox 在存在平台通知 UI 的地方使用它。

在 Settings > Push & In-App > Web 中设置默认图标 URL。请参阅 Web SDK 设置。您还可以使用仪表板或 REST API 按通知覆盖图标。请参阅使用非默认图标发送通知。

Android Web 推送徽章图标

在 Android 上，当没有足够空间显示完整通知时，Chrome Web 推送可以在状态栏中显示较小的徽章图标。OneSignal 通过 chrome_web_badge 发送它，该参数对应 Notifications API 的 badge 选项。Android 上的 Chrome 会使用此徽章。如果您不设置徽章，Chrome 会使用浏览器图标。其他浏览器通常显示浏览器图标。请参阅 Notification: badge。这不是应用图标徽章（圆点或数字）。有关这些，请参阅徽章。请将徽章视为单色图标。MDN 指出 Android 会自动遮罩该图像。请使用透明背景上的正方形 PNG 剪影（规则与 Android 小图标相同）。避免文本、精细细节和全彩艺术作品。 MDN 建议约 96×96 像素，以便图像在 4x 下仍然清晰。72×72 是通常的最小尺寸（3x 下的 24dp）。更大的图像会被缩小。

徽章图标在 Android 状态栏中的显示示例。

使用非默认图标发送通知

从 OneSignal 仪表板或 REST API 发送推送时，您可以覆盖 Android、Amazon、Huawei 和 Web 推送的默认图标。您无法覆盖 iOS 通知的图标。

REST API 参数

Android、Amazon 和 Huawei：

string

不带文件扩展名的图标资源名称。该图像必须存在于与默认小图标相同的项目文件夹中。不支持远程 URL。请参阅如何添加 Android 默认图标。Amazon 使用 adm_small_icon。Huawei 使用 huawei_small_icon。示例："small_icon": "my_custom_icon"

string

不带文件扩展名的图标资源名称，或远程 URL。如果使用资源名称，该图像必须存在于与默认大图标相同的项目文件夹中。请参阅如何添加 Android 默认图标。Amazon 使用 adm_large_icon。Huawei 使用 huawei_large_icon。示例："large_icon": "my_custom_icon"

Web 推送：

string

图像资源的直接 URL。Firefox 使用 firefox_icon。示例："chrome_web_icon": "https://example.com/my_custom_icon.png"

string

用作 Chrome Web 通知的 Android 状态栏徽章的图像资源的直接 URL。示例："chrome_web_badge": "https://example.com/badge.png"

仪表板

在 Messages > Push > New Push 或 Templates 中，打开特定于平台的选项。对于 Android、Amazon 和 Huawei，如果文件存在于与默认图标相同的项目路径中，请设置不带文件扩展名的图标名称。对于大通知图标，您还可以提供直接 URL。

OneSignal 仪表板，覆盖默认图标的位置。

常见问题

为什么我的 Android 小图标显示为白色或灰色方块？

图像没有正确的透明度。Android 仅使用 alpha 通道渲染小通知图标。具有实心背景的完全不透明像素会显示为填充方块。请使用 Android Asset Studio 将图标重新生成为透明背景上的单色剪影。

为什么显示 OneSignal 铃铛图标而不是我的自定义图标？

小图标的一个或多个所需密度变体缺失、放置在错误的 drawable 目录中或命名不正确。请包含所有五个尺寸（MDPI 到 XXXHDPI），并使用确切的文件名 ic_stat_onesignal_default。有关正确路径，请参阅如何添加 Android 默认图标。

为什么通知显示我的应用图标而不是我的小图标？

从 Android 17（API 37）开始，Android 默认在通知上显示应用的启动器图标。小图标仍会显示在状态栏中。要在通知上显示小图标，请在通知服务扩展中设置 EXTRA_PREFER_SMALL_ICON extra。请参阅通知上的启动器图标。

我可以按消息更改 iOS 通知图标吗？

不可以。iOS 始终将您的应用图标用于推送通知。APNs 负载没有图标字段。更改图标需要更新您的应用图标资源并发布新的应用版本。消息和通话应用只能通过采用通信通知来显示发送者头像。

我的 Web 推送图标应该是什么尺寸？

使用 256×256 像素的正方形 PNG、JPG 或非动画 GIF。不同的浏览器和操作系统可能会裁剪或缩放图标，但 256×256 是在 Chrome、Firefox、Edge 和 Safari 之间最一致的尺寸。

我可以为 Android 小图标使用 URL 吗？

不可以。Android 小图标必须是与您的应用捆绑的本地资源文件。只有大图标支持远程 URL。

如何在 Expo 中添加通知图标？

使用 onesignal-expo-plugin，在 app.json 或 app.config.js 中提供一个 96×96 的小图标 PNG 和一个 256×256 的大图标 PNG。插件会在构建时生成密度变体。有关配置，请参阅 Expo 选项卡。

我需要将默认图标上传到 OneSignal 仪表板吗？

不需要。默认通知图标捆绑在您的应用二进制文件中，而不是上传到 OneSignal。您将它们添加到项目的资源目录（或 Expo 的插件配置），OneSignal SDK 会自动使用它们。OneSignal 仪表板仅允许您针对 Android 和 Web 推送按消息覆盖图标。

图像和富媒体

将大图像、GIF 和视频附加到推送通知。

Android SDK 设置

安装 Android SDK，然后在您的 drawable 文件夹中添加默认通知图标。

React Native / Expo SDK 设置

在 OneSignal Expo 插件中配置 smallIcons 和 largeIcons。

Android 通知类别

创建和管理用于声音、振动和重要性的 Android 通知渠道。

Web SDK 设置

在 Settings > Push & In-App > Web 中设置默认图标 URL。

创建消息 API

使用 REST API 发送带有自定义图标的推送通知。

开始使用和设置

消息渠道

旅程

受众和自定义事件

分析和集成

隐私和安全

Android 通知图标

小通知图标

通知上的启动器图标（Android 17）

小图标强调色

大通知图标

如何添加 Android 默认图标

iOS 通知图标

通信通知

Web 通知图标

Android Web 推送徽章图标

使用非默认图标发送通知

REST API 参数

仪表板

常见问题

为什么我的 Android 小图标显示为白色或灰色方块？

为什么显示 OneSignal 铃铛图标而不是我的自定义图标？

为什么通知显示我的应用图标而不是我的小图标？

我可以按消息更改 iOS 通知图标吗？

我的 Web 推送图标应该是什么尺寸？

我可以为 Android 小图标使用 URL 吗？

如何在 Expo 中添加通知图标？

我需要将默认图标上传到 OneSignal 仪表板吗？

相关页面

图像和富媒体

Android SDK 设置

React Native / Expo SDK 设置

Android 通知类别

Web SDK 设置

创建消息 API

​Android 通知图标

​小通知图标

​通知上的启动器图标（Android 17）

​小图标强调色

​大通知图标

​如何添加 Android 默认图标

​iOS 通知图标

​通信通知

​Web 通知图标

​Android Web 推送徽章图标

​使用非默认图标发送通知

​REST API 参数

​仪表板

​常见问题

​为什么我的 Android 小图标显示为白色或灰色方块？

​为什么显示 OneSignal 铃铛图标而不是我的自定义图标？

​为什么通知显示我的应用图标而不是我的小图标？

​我可以按消息更改 iOS 通知图标吗？

​我的 Web 推送图标应该是什么尺寸？

​我可以为 Android 小图标使用 URL 吗？

​如何在 Expo 中添加通知图标？

​我需要将默认图标上传到 OneSignal 仪表板吗？

​相关页面

图像和富媒体

Android SDK 设置

React Native / Expo SDK 设置

Android 通知类别

Web SDK 设置

创建消息 API

Android 通知图标

小通知图标

通知上的启动器图标（Android 17）

小图标强调色

大通知图标

如何添加 Android 默认图标

iOS 通知图标

通信通知

Web 通知图标

Android Web 推送徽章图标

使用非默认图标发送通知

REST API 参数

仪表板

常见问题

为什么我的 Android 小图标显示为白色或灰色方块？

为什么显示 OneSignal 铃铛图标而不是我的自定义图标？

为什么通知显示我的应用图标而不是我的小图标？

我可以按消息更改 iOS 通知图标吗？

我的 Web 推送图标应该是什么尺寸？

我可以为 Android 小图标使用 URL 吗？

如何在 Expo 中添加通知图标？

我需要将默认图标上传到 OneSignal 仪表板吗？

相关页面