Skip to main content

推送通知总览

推送通知，使得开发者可以即时地向其应用程序的用户推送通知或者消息，与用户保持互动，从而有效地提高留存率，提升用户体验。平台提供整合了 Android 推送、iOS 推送的统一推送服务。

除了通过 iOS、Android SDK 做推送服务之外，你还可以通过 REST API 来发送推送请求。

使用推送服务前，需在 应用 > 设置 > 安全中心 开启推送服务，此开关有三分钟的延迟。

基本概念​

Installation​

Installation 表示一个允许推送的设备的唯一标示，对应数据管理平台中的 _Installation 表。它就是一个普通的 LCObject，主要属性包括:

名称适用平台描述
badgeiOS呈现在应用图标右上角的红色圆形数字提示，例如待更新的应用数、未读信息数目等。
channels设备订阅的频道。频道名称只能包含大小写英文字母、数字、下划线（_）、连字符（-）、等号（=）、汉字（中日韩统一表意文字）。
deviceProfile在应用有多个 iOS 推送证书或多个 Android 混合推送配置的场景下，deviceProfile 用于指定当前设备使用的证书名或配置名。其值需要与 开发者中心 > 你的游戏 > 游戏服务 > 云服务 > 推送通知 > 设置 内配置的证书名或配置名对应，否则将无法完成推送。deviceProfile 的值必须以字母开头，由大小写字母、数字和下划线组成的字符串，或为空值。deviceProfile 是特殊字段，只支持 equals 查询。
deviceTokeniOSAPNs 推送的唯一标识符
apnsTopiciOS基于 Token Authentication 的推送需要设置该字段。iOS SDK 会自动读取 iOS 应用的 bundle ID 作为 apnsTopic。但以下情况需要手工指定：1. 使用低于 v4.2.0 的 iOS SDK 版本；2. 不使用 iOS SDK（如 React Native）；3. 使用不同于 bundle ID 的 topic。
deviceType设备类型，目前支持 ios、android。
installationIdAndroidSDK 为每个 Android 设备产生的唯一标识符
timeZone字符串，设备设定的时区

Notification​

对应 开发者中心 > 你的游戏 > 游戏服务 > 云服务 > 推送通知 > 推送记录 里的一条记录，表示一条推送消息，它包括下列属性：

名称适用平台描述
notificationId推送消息 ID
msg本次推送的消息内容，JSON 对象，详见消息内容参数。
invalidTokensiOS本次推送遇到多少次由 APNs 返回的 INVALID TOKEN 错误。如果这个数字过大，请留意证书是否正常。
prodiOS使用什么环境证书。dev 表示开发证书，prod 表示生产环境证书。
status本次推送的状态，in-queue 表示仍然在队列，done 表示完成，scheduled 表示定时推送任务等待触发中。
devices本次推送目标设备数。这个数字不是实际送达数，而是处理本次推送请求时在 _Installation 表中符合查询条件且有效的总设备数。有效是指 _Installation 表的 valid 字段为 true 且 updatedAt 字段时间在最近三个月以内。目标设备数可能会包含大量的非活跃用户（如已卸载 App 的用户），这部分用户可能无法收到推送。
successes本次推送成功设备数。推送成功对普通 Android 设备来说指目标设备收到了推送，对 iOS 设备或使用了混合推送的 Android 设备来说指消息成功推送给了 Apple APNs 或设备对应的混合推送平台。此外还有 [lc/ios/fcm/hms/mi/oppo/vivo/meizu]Successes 等分别代表通过各渠道推送成功的设备数。
where本次推送查询 _Installation 表的条件，符合这些查询条件的设备将接收本条推送消息。
errors本次推送过程中的错误信息。
from-servicepush 表示是直接发送的推送消息，rtm 表示是 RTM 离线推送消息。
push-time定时推送的发送时间

推送本质上是根据一个 query 条件来查询 _Installation 表里符合条件的设备，然后将消息推送给设备。因为 _Installation 是一个可以完全自定义属性的 Key-Value Object，因此可以实现各种复杂条件推送，例如频道订阅、地理位置信息推送、特定用户推送等。

对于 devices 和 successes 这两个属性，当 devices 值为 0 时，表示没有找到任何符合目标条件的设备，需要检查一下推送查询条件，这时没有设备能收到推送通知；当 devices 值不为 0 时，该值仅仅说明找到了这么多符合条件的设备，但并不保证这些设备都能收到推送通知，所以 successes 很可能是会小于 devices 的。特别是当查询出来的设备中含有大量的非活跃设备时，successes 可能会和 devices 有很大差距。

如果某个设备不想收到推送提醒，可以将 _Installation 表中相应安装对象的 valid 字段修改为 false。

注意：我们只保留最近一周的推送记录，并会对过期的推送记录定时进行清理。推送记录清理和推送消息过期时间无关，也就是说即使推送记录被清理，没有过期的推送消息依然是有效的，目标用户依然是能够收到消息。推送过期时间设置请参考推送 REST API 使用指南的《过期时间和定时推送》一节。

Unity 推送​

请阅读 Unity 推送指南。

Unreal 推送​

请阅读 Unreal 推送指南。

iOS 推送​

请阅读 iOS 推送指南。

Android 推送​

由于 Android 系统权限控制越来越严，推送服务自有通道的推送到达率受到影响。 因此，建议商用版应用使用我们的「混合推送」方案，该方案对接了 FCM 的接口，让开发者通过统一的 API 完成推送任务。 详见 Android 混合推送指南。

如果想要使用推送服务自有通道推送，请阅读 Android 推送指南。

使用 REST API 推送消息​

请阅读推送 REST API 使用指南。

云引擎下通过 JavaScript SDK 创建推送​

JavaScript SDK 也提供了创建推送的接口，使用场景主要面向云引擎。请参考 SDK 的 API 文档 AV.Push。 这里举两个简单的例子：

推送给所有订阅了 public 频道的设备：

AV.Push.send({
  channels: [ 'public' ],
  data: {
    alert: 'public message'
  }
});

如果希望按照某个 _Installation 表的查询条件来推送，例如推送给某个 installationId 的 Android 设备，可以传入一个 AV.Query 对象作为 where 条件：

const query = new AV.Query('_Installation');
query.equalTo('installationId', installationId);
AV.Push.send({
  where: query,
  data: {
    alert: 'Public message'
  }
});