APN Sender 技术文档

1. 安装指南

1.1 使用 Gemfile 安装

在你的 Rails 应用的 Gemfile 中添加以下代码：

gem 'apn_sender', require: 'apn'

然后执行以下命令来安装 gem：

$ bundle

1.2 手动安装

你也可以手动安装 apn_sender gem：

$ gem install apn_sender

1.3 添加 Rake 任务

为了使用一些有用的 Rake 任务来运行 worker，请在你的 Rakefile 中添加以下代码：

require 'apn/tasks'

2. 项目的使用说明

2.1 使用后台处理器

apn_sender 支持使用 Resque 或 Sidekiq 来发送异步消息。强烈建议使用 Sidekiq，因为它使用连接池来管理 Apple 的 socket 连接。

2.2 从应用程序中排队消息

要从你的 Rails 应用程序中排队发送消息到 Apple 的推送通知服务，可以使用以下代码：

APN.notify_async(token, opts_hash)

其中 token 是接收通知的 iPhone 的唯一标识符，opts_hash 可以包含以下键：

• :alert：要发送的提醒内容。
• :badge：要发送的徽章数字。
• :sound：要播放的声音文件，或 true 以播放默认声音。
• :content_available：使远程通知作为“静默”通知。

如果包含其他键，它们将被作为自定义数据传递给应用程序。

2.3 发送排队消息

将你的 apn_development.pem 和 apn_production.pem 证书从 Apple 放置在 RAILS_ROOT/config/certs 目录中。

你还可以配置一些额外的设置：

APN.root = 'RAILS_ROOT/config/certs' # 证书文件夹的根目录
APN.certificate_name = 'apn_production.pem' # 证书文件名
APN.host = 'apple host (开发环境中默认使用沙盒 URL)'
APN.password = 'certificate_password'
APN.pool_size = 1 # 连接池中的连接数
APN.pool_timeout = 5 # 连接池的超时时间（秒）
APN.logger = Logger.new(File.join(Rails.root, 'log', 'apn_sender.log'))
APN.truncate_alert = true # 启用对超出最大允许字节的提醒进行截断
APN.backend = :sidekiq # 使用 sidekiq 后台处理器

检查 logs/apn_sender.log 文件以进行调试输出。

2.4 检查 Apple 的反馈服务

由于推送通知是“发送即忘”的操作，Apple 需要一种方式来确保他们的网络不会被无效消息堵塞。因此，他们提供了反馈服务。

你可以通过以下代码连接到 Apple 的反馈服务并获取失效的设备令牌：

feedback = APN::Feedback.new()

tokens = feedback.tokens # 设备令牌数组
tokens.each do |token|
  # 自定义逻辑以停止向此令牌发送通知
end

如果你需要知道 Apple 确定每个令牌失效的确切时间，可以使用以下代码：

items = feedback.data # APN::FeedbackItem 元素数组
items.each do |item|
  item.token
  item.timestamp
  # 自定义逻辑
end

3. 项目 API 使用文档

3.1 APN.notify_async(token, opts_hash)

• token：接收通知的 iPhone 的唯一标识符。
• opts_hash：包含通知选项的哈希表。

3.2 APN::Feedback.new()

• 返回一个 APN::Feedback 对象，用于连接 Apple 的反馈服务并获取失效的设备令牌。

3.3 feedback.tokens

• 返回一个包含失效设备令牌的数组。

3.4 feedback.data

• 返回一个包含 APN::FeedbackItem 元素的数组，每个元素包含失效的设备令牌和失效时间。

4. 项目安装方式

4.1 通过 Gemfile 安装

在 Gemfile 中添加 gem 'apn_sender', require: 'apn'，然后运行 bundle 命令。

4.2 手动安装

运行 gem install apn_sender 命令手动安装。

4.3 添加 Rake 任务

在 Rakefile 中添加 require 'apn/tasks' 以启用 Rake 任务。