首先注册 App ID。如果你已经注册过带有推送通知 App ID,可以跳过以下步骤:
为已有的 App ID 开启推送通知的步骤如下:
Token Authentication 是 APNs 新推出的推送鉴权方式。它相对老的证书鉴权方式有如下优势:
想进一步了解其相关内容请参看 APNs 文档。
我们推荐所有用户都使用这种新的鉴权方式来发推送消息。
点击 Membership
找到 Team ID 一栏,将其记下来以备后用。
点击 Certificates, Identifiers & Profiles
点击下图中红色边框内的加号按钮
根据您的需要自行填写 Key Description 并勾选 APNs 后点击最下面的 Continue 按钮。
点击 Confirm 按钮继续下一步。
点击 Download 将生成好的 Auth Key 下载到本地,并记录 Key ID 备用。
进入 控制台 > 消息 > 推送 > 设置,然后就可以看到下面的页面:
点击 新增 Token Authentication 后弹出对话框:
在弹出的对话框内填入 Team ID、Key ID、Topics,并将上一步下载到本地的 Auth Key 文件上传。
点击 创建 之后就完成了上传 Token Authentication Key 的工作。
在 LeanCloud 平台,Token Authentication 鉴权方式和老的证书鉴权方式是互斥的,一旦配置了 Token Authentication 则应用下所有推送均会使用 Token Authentication 方式进行,所以请确保为所有需要发推送的 App 都添加了 Token Authentication 配置。
如果目标推送设备中有使用版本低于 v4.2.0 的 iOS SDK,请在调用推送接口发推送时主动带上 topic 参数。用法请参考 推送消息接口。
每个 App ID 都需要单独的客户端 SSL 证书来和 APNs 通信。从 2015 年 12 月 17 日起,APNs 服务全面支持 HTTP/2 协议,推送证书也进行了相应的调整,即推出了 Universal Push Notification Client SSL 证书,以下简称 Universal 推送证书。通过下图中红框标注的 Apple Push Notification service SSL (Sandbox & Production) 这种方式创建的推送证书就是「Universal 推送证书」。
我们推荐使用「Universal 推送证书」来进行推送服务。
图中其他方式就叫做「非 Universal 方式」,以下简称 非 Universal 推送证书:
要使用 Universal 推送证书,LeanCloud iOS SDK 需要更新到 v3.2.8 以上的版本,以获得更快速的推送效果。
请按以下步骤创建「Universal 推送证书」:
勾选 Production 栏下的 Apple Push Notification service SSL (Sandbox & Production),点击下一步。
从 App ID 下拉菜单中选择相应的 App ID,点击下一步。
这时会出现 About Creating a Certificate Signing Request (CSR)。
根据它的说明创建 Certificate Signing Request。
点击下图中的 Choose File 按钮
.certSigningRequest
双击打开证书,证书打开时会启动 Keychain Access / 钥匙串访问 工具。 在钥匙串访问工具中,你的证书会显示在 证书 中。注意选择左下角的 证书 和左上角的 登录。
「非 Universal 推送证书」的申请步骤与以上类似。
右键点击证书,这里请注意确认右键点击的是证书,不要 展开证书后右键点击证书的专用密钥。
选择 导出 / Export,选择保存格式为 .p12。这时程序会提示你输入密码来保护导出的证书,请不要输入密码,让两个输入框为空,点击 OK。
.p12
接着又会弹出一个对话框,要求输入 macOS 账户的密码来允许从 Keychain Access 中导出,请填写密码并点击 允许 / Allow。
在 Xcode 工程中开启推送权限:
将「Universal 推送证书」上传到图中的 生产证书 中。
根据你的证书类别进行上传。这里请注意区分证书的类别,测试环境证书和生产环境证书请勿混淆。
配置推送证书,最简单的方式就是将刚才生成的「Universal 推送证书」直接上传。当然也可以自己生成一个测试证书。
上传测试证书后,那么就可以在控制台看到生产证书和测试证书都上传完成:
如果无法上传推送证书,通常是因为证书有问题,一般由下列原因导致:
验证导出的证书是不是推送证书有两种方法:
目前 LeanCloud 只接受 p12 格式的证书。因此在导出证书时,必须选择 p12 作为导出格式。
p12
上传证书时,LeanCloud 会进一步校验证书,帮助开发者发现错误。上传程序会检查证书的名字是否包含以下前缀:
Apple Push Services
Apple Development IOS Push Services
Apple Production IOS Push Services
Pass Type ID
如果程序发现证书的名字中不包含以上前缀,则校验失败,证书将无法上传。
Apple 未来可能会修改推送证书的名字前缀,我们会及时更新前缀列表,同时也欢迎大家来补充。
开发者如果使用过期证书进行推送,会遇到「The iOS certificate file is expired or disabled」的错误提示。
LeanCloud 后端在收到推送请求时都会去检查 prod 参数指明的证书是否过期,没有 prod 则默认检查正式环境证书,如果发现过期并且 query 条件查出的目标设备可能存在 iOS 设备,就直接拒绝本次推送。
prod
一种解决方法是替换过期的证书,另一种方法是在 query 条件中通过 deviceType 字段明确指定 _Installation 表中设备类型为非 iOS 设备来推送,方法参见 消息推送总览 · 通过查询条件发推送。
deviceType
_Installation
按以下步骤来验证 App ID 的推送服务是否打开:
如果下图中红色方框中显示 Enabled,表示 App ID 的推送证书已配置好。
iOS 推送证书设置指南
注册 App ID
首先注册 App ID。如果你已经注册过带有推送通知 App ID,可以跳过以下步骤:
开启推送通知
为已有的 App ID 开启推送通知的步骤如下:
创建 Token Authentication
Token Authentication 是 APNs 新推出的推送鉴权方式。它相对老的证书鉴权方式有如下优势:
想进一步了解其相关内容请参看 APNs 文档。
我们推荐所有用户都使用这种新的鉴权方式来发推送消息。
获取 Team ID
点击 Membership
找到 Team ID 一栏,将其记下来以备后用。
创建 Token Authentication Key
点击 Certificates, Identifiers & Profiles
点击下图中红色边框内的加号按钮
根据您的需要自行填写 Key Description 并勾选 APNs 后点击最下面的 Continue 按钮。
点击 Confirm 按钮继续下一步。
点击 Download 将生成好的 Auth Key 下载到本地,并记录 Key ID 备用。
上传 Token Authentication Key
进入 控制台 > 消息 > 推送 > 设置,然后就可以看到下面的页面:
点击 新增 Token Authentication 后弹出对话框:
在弹出的对话框内填入 Team ID、Key ID、Topics,并将上一步下载到本地的 Auth Key 文件上传。
点击 创建 之后就完成了上传 Token Authentication Key 的工作。
在 LeanCloud 平台,Token Authentication 鉴权方式和老的证书鉴权方式是互斥的,一旦配置了 Token Authentication 则应用下所有推送均会使用 Token Authentication 方式进行,所以请确保为所有需要发推送的 App 都添加了 Token Authentication 配置。
如果目标推送设备中有使用版本低于 v4.2.0 的 iOS SDK,请在调用推送接口发推送时主动带上 topic 参数。用法请参考 推送消息接口。
创建推送证书(不推荐使用)
每个 App ID 都需要单独的客户端 SSL 证书来和 APNs 通信。从 2015 年 12 月 17 日起,APNs 服务全面支持 HTTP/2 协议,推送证书也进行了相应的调整,即推出了 Universal Push Notification Client SSL 证书,以下简称 Universal 推送证书。通过下图中红框标注的 Apple Push Notification service SSL (Sandbox & Production) 这种方式创建的推送证书就是「Universal 推送证书」。
我们推荐使用「Universal 推送证书」来进行推送服务。
图中其他方式就叫做「非 Universal 方式」,以下简称 非 Universal 推送证书:
要使用 Universal 推送证书,LeanCloud iOS SDK 需要更新到 v3.2.8 以上的版本,以获得更快速的推送效果。
创建 Universal 推送证书
请按以下步骤创建「Universal 推送证书」:
点击 Certificates, Identifiers & Profiles
点击下图中红色边框内的加号按钮
勾选 Production 栏下的 Apple Push Notification service SSL (Sandbox & Production),点击下一步。
从 App ID 下拉菜单中选择相应的 App ID,点击下一步。
这时会出现 About Creating a Certificate Signing Request (CSR)。
根据它的说明创建 Certificate Signing Request。
点击下图中的 Choose File 按钮
.certSigningRequest
文件,生成 APNs Push Certificate。双击打开证书,证书打开时会启动 Keychain Access / 钥匙串访问 工具。 在钥匙串访问工具中,你的证书会显示在 证书 中。注意选择左下角的 证书 和左上角的 登录。
「非 Universal 推送证书」的申请步骤与以上类似。
导出证书
右键点击证书,这里请注意确认右键点击的是证书,不要 展开证书后右键点击证书的专用密钥。
选择 导出 / Export,选择保存格式为
.p12
。这时程序会提示你输入密码来保护导出的证书,请不要输入密码,让两个输入框为空,点击 OK。接着又会弹出一个对话框,要求输入 macOS 账户的密码来允许从 Keychain Access 中导出,请填写密码并点击 允许 / Allow。
在 Xcode 工程中开启推送权限:
上传证书
进入 控制台 > 消息 > 推送 > 设置,然后就可以看到下面的页面:
将「Universal 推送证书」上传到图中的 生产证书 中。
根据你的证书类别进行上传。这里请注意区分证书的类别,测试环境证书和生产环境证书请勿混淆。
配置推送证书,最简单的方式就是将刚才生成的「Universal 推送证书」直接上传。当然也可以自己生成一个测试证书。
上传测试证书后,那么就可以在控制台看到生产证书和测试证书都上传完成:
上传证书失败
如果无法上传推送证书,通常是因为证书有问题,一般由下列原因导致:
验证导出的证书是不是推送证书有两种方法:
目前 LeanCloud 只接受
p12
格式的证书。因此在导出证书时,必须选择p12
作为导出格式。上传证书时,LeanCloud 会进一步校验证书,帮助开发者发现错误。上传程序会检查证书的名字是否包含以下前缀:
Apple Push Services
Apple Development IOS Push Services
Apple Production IOS Push Services
Pass Type ID
如果程序发现证书的名字中不包含以上前缀,则校验失败,证书将无法上传。
Apple 未来可能会修改推送证书的名字前缀,我们会及时更新前缀列表,同时也欢迎大家来补充。
证书过期
开发者如果使用过期证书进行推送,会遇到「The iOS certificate file is expired or disabled」的错误提示。
LeanCloud 后端在收到推送请求时都会去检查
prod
参数指明的证书是否过期,没有prod
则默认检查正式环境证书,如果发现过期并且 query 条件查出的目标设备可能存在 iOS 设备,就直接拒绝本次推送。一种解决方法是替换过期的证书,另一种方法是在 query 条件中通过
deviceType
字段明确指定_Installation
表中设备类型为非 iOS 设备来推送,方法参见 消息推送总览 · 通过查询条件发推送。验证推送服务状态
按以下步骤来验证 App ID 的推送服务是否打开:
如果下图中红色方框中显示 Enabled,表示 App ID 的推送证书已配置好。