Notification API 开发
文章信息
Contents |
第一步：注册你的服务
开始开发你的服务和应用的通知功能前，需要再Nokia的主机基础设施上注册你的新服务。注册服务得到一些服务的凭证信息（service credential），包括，一个服务ID（Service ID）和一个服务密码（Service Secret）， 还包括一个应用ID（Application ID）
服务ID在通知服务器（Notification Sever）上唯一的标识你的服务， 服务密码由Nokia生成。你的服务必须使用这些凭证信息，在通知服务器上注册和认证，然后才能开始发通知。
应用ID在通知服务器上唯一的标识你的应用。 在开发者控制台请求一个新的服务ID，应用ID，和服务密码，只需要在创建新服务一栏， 填入一个未被用过的服务ID，再点创建即可，服务密码由Nokia生成，应用ID是服务ID的镜像，不需要额外设置。服务ID的命名规则参见穿件按钮旁边的帮助.
有了服务ID，服务密码，应用ID后，你可以进行[第二步：给你的服务添加通知功能]。
这里创建的凭证信息，还只能用于沙盒测试环境（sandbox environment），要在获取在产品环境（product environment）中使用的凭证信息，请参考后面第五步：发布你的应用。
第二步：给你的服务添加通知功能
通知服务API（Notification Service API）通过一个HTTP REST接口 提供访问通知服务器的方法。如下图所示，你的服务通过这个接口像你的客户端应用发通知消息。
要发送一个通知，服务必须提供以下信息给服务器：
- 服务凭证信息
- 通知内容
- 接收者
通知API提供唤醒功能，即在收到通知 而用户没正在使用应用的时候 激活客户端应用。这可以通过在服务API和客户端API设置参数来做。
服务凭证信息
服务必须在通知服务器上认证，即向服务器提交服务ID和服务密码（注册的时获得）。 服务发出的所有推送消息都经过HTTPS数字签名认证
通知内容
通知的内容也称作有效载荷（payload），可以是任意类型，文本，图片等，必须小于1.5kB。
接收者
通知REST API(Notifications REST API )支持通过下面的方法设定接收者：
- 发给单个用户，使用接收者的用户ID(user ID,也叫做JID)和目标应用的应用ID (同一个用户可能安装了多个支持通知API的应用)。
- 发给单个用户，使用唯一的通知ID（也叫做NID），此通知ID有客户端提供。
- 批量发送通知，使用JID或NID。
使用通知ID
通知ID，对每个用户的每个应用是唯一的，给你的应用的用户额外的隐私保护。因为这样做使得 你的服务发通知给你的用户时，不知道通知ID以外的信息。
下面的图演示了如何在你的应用中实现。第1步 客户端应用运行时请求通知ID，接着第2步应用将通知ID发给你的服务，这样在第3，4步可使用NID来实现私密传送的方法。
你必须保证你的客户端将通知ID发给了你的服务， ID传送在通知服务连接之外，需要自己完成。 注意一个通知ID和一个Nokia账号绑定。 如果用户更换了另一个Nokia账号，那么原来的通知ID将失效。这时应用要重新请求一个通知ID，并交给服务。
通知REST API指南
使用通知REST API不需要任何安装，你只需很简单在你的服务中的使用REST API来给客户端发通知，下表列出了发送通知的两个REST API调用：
| 认证 | SSL+HTTP Digest 登陆名：服务ID |
| URL | /nnapi/1.0/jid/{JID} /nnapi/1.0/nid/{Notification ID} |
| 方法 | POST |
通知参数
REST API主要的参数如下：
| 参数 | 描述 |
| toapp | 目标应用的ID |
| payload | 通知的内容 |
| wakeup | 设定在收到消息时是否激活还没有运行的应用，注意只有服务API和客户端API都设定了唤醒参数，通知才会显示 |
| ctype | 设定内容的类型，表示为mime-type（如:application/xml, text/plain),最大长度255 byte |
| enc | 定义消息内容的编码（如：Base64），最大长度 32byte |
HTTP 请求连接
你的应用需要使用一个持久化的TCP/TLS连接来处理HTTP请求。这点对产品环境尤为重要，这里连接必须是持久化的。
开始服务开发
现在可以开始开发你的服务，可参考示例代码，这些示例服务用， Java,Python和Perl，PHP写成，可以在这些示例基础上构造你的应用。
- Java示例
- Python示例
- Perl示例
- [Using PHP and cURL to send a notification using Notification Service API PHP示例]
运行示例的准备
这些示例假设你已经注册了你的服务，获得了服务ID，服务密码和应用ID，如果你没做，请回到第一步，注册你的服务。 使用通知RESTAPI与客户端通信的唯一需要是 服务使用一个 有HTTPS能力的HTTP客户端支持摘要认证（digest authorization）。这些例子演示了如何构照一个这样一个HTTP客户端，以及这个HTTP客户端如何调用API方法。
用Curl测试REST API
你可以使用下面的curl命令来测试服务账号和凭证信息。curl是一个URL传输的命令行工具，在大多数平台上都有，包括Linux，Windows和Mac OS。 运行下面命令来测试你的服务：
curl --digest -u "<SERVICE_ID>:<SERVICE_SECRET>" https://alpha.one.ovi.com/nnapi/1.0/ping
其中 <SERVICE_ID> 和 <SERVICE_SECRET> 是你前面注册的服务的凭证信息：服务ID和服务密码 如果请求成功，你会得到一个HTTP结果200，其他返回值参看通知REST API 协议
用curl发送一个通知
使用下面的命令可以通过 通知REST API推送一条消息：
curl --digest -u "<SERVICE_ID>:<SERVICE_SECRET>" -d "toapp=<APPLICATION_ID>" -d "payload=Test notification via Notifications API" https://alpha.one.ovi.com/nnapi/1.0/jid/<CLIENT_JID>
其中 <SERVICE_ID>, <SERVICE_SECRET>, 和 <APPLICATION_ID>是前面注册的账号信息。<CLIENT_JID> 参数定义了通知的接收者，可以是一个Nokia账户ID。命令将发送文字 "Test notification via Notifications API" 到接收者。
准备需求
通知REST API不依赖于平台和编程语言。因此你的服务可以用你习惯的环境和工具开发。支持大多数平台 包括Linux，Windows和Mac OS。通知REST API,只能通过 HTTPS协议访问，因此你的服务需要 就有HTTPS能力的HTTP客户端。 你的服务需要通过连接下面的链接来访问通知沙盒REST API：https://alpha.one.ovi.com 。查看示例应用，来实现你应用中的连接。
限制
通知REST API的目的是，提供一个服务和客户端应用交流的通道，Nokia并不提供寄存服务应用本身。 另外，每个服务每小时最多能发送一定量的消息，这个限量随着注册到服务上的客户端NID增加而增加。 服务可以通过限制查询请求 来查看发送限额的状态。 如果你的服务器达到了小时内限制，这时请求返回值是503，直到新的一小时周期开始，注意由于小时内限制随着用户数增加而增加，同样应用模式下，服务应该不会遇到问题。
第三步：客户端开发
设备上的应用通过 通知客户端API从通知服务器 注册和接收通知。本章提供添加通知在你应用的概念性的信息,包括下面几个主题:
- 支持的设备
- 客户端通知应用的生命周期
- 使用通知ID
- 通知的用户界面和唤醒功能
支持的设备
客户端通知API目前支持 很多支持QtAPI的Symbian设备，将在未来某版支持Meego设备。 支持的设备列表
客户端通知应用的生命周期
如下图所示，每个通知客户端应用生命周期中经历3个状态：离线，连接和在线。实际中，当一个应用打开时，希望它应该是在线状态，这意味着它成功在通知Enabler上注册成功，且Enabler已建立一个活动的连接。在这个状态下，应用可以接收到通知，调用APId的方法。
使用通知ID
通知ID，对每个用户的每个应用是唯一的，给你的应用的用户额外的隐私保护。因为这样做使得 你的服务发通知给你的用户时，不知道通知ID以外的信息。
下面的图演示了如何在你的应用中实现。第1步 客户端应用运行时请求通知ID，接着第2步应用将通知ID发给你的服务，这样在第3，4步可使用NID来实现私密传送的方法。
你必须保证你的客户端将通知ID发给了你的服务， ID传送在通知服务连接之外，需要自己完成。 注意一个通知ID和一个Nokia账号绑定。 如果用户更换了另一个Nokia账号，那么原来的通知ID将失效。这时应用要重新请求一个通知ID，并交给服务。
通知的用户界面和唤醒功能
通知API开发套件包含一个通知用户界面（UI），开发者可以利益欧诺个这个预制的通知UI屏幕来简化显示通知的开发过程。下图显示了通知UI应用的屏幕，收到通知的应用将其接口图片文字列在表中，用户点击后进一步显示应用中的通知。
通知界面UI应用使用应用唤醒功能，可在收到消息时激活客户端应。
在你的应用中实现通知
在客户端应用中客户端API实现以下功能：
- 把你的应用注册到手机上的通知引擎， 通知引擎负责维持一个与通知服务器之间的活跃的连接。一个通知引擎可以处理多个客户端应用。
- 获取通知ID
- 接收通知信息
例子代码
第四步：测试你的服务
Nokia提供下面两种测试环境：
- 沙盒环境：使用托管在Nokia的沙盒环境来开发和测试你的应用。在这个环境，服务发送通知到客户端应用，如同工作在产品环境一样。但你第一次注册你的服务，服务被托管在沙盒环境，所有工具指向沙盒。
- 产品环境：当你的服务测试完毕，可以将其移至产品环境。服务至少要在沙盒环境测试5天以上才能移到产品环境。
下图说明这两种环境：
Nokia 提供测试服务和客户端应用的工具：
- 服务端API工具
*你可以用服务端示例来测试使用REST API发通知消息。 *你可以使用curl命令行工具来测试你的服务凭证信息，发送通知到一个客户端应用。
- 客户端API工具
*你可以用客户端示例应用和Qt模拟器来测试使用客户端API接收通知。 *你可以使用沙盒环境的开发者控制台来向客户端应用发通知
环境选择
默认情况，设备配置成运行在产品环境中。要在沙盒环境测试你的设备，或者要从沙盒切换回产品环境，你可以使用环境选择应用。这个应用包含在通知开发套件中。
在这里查看安装和使用说明。
第五步：发布你的服务
发布你的应用需要两步：
- 申请一个产品环境的服务密码。
- 在Ovi商店上发布和部署你的应用。
申请一个产品环境的服务密码
当你的准备发布你的应用时，你需要申请一个产品环境的服务密码，用来在真实世界环境中发通知消息。 申请产品环境的服务密码过程： 进入开发者控制台.选择你的服务，点击运用产品环境（Apply to production）。在申请服务移至产品窗口，在服务信息栏中提交关于你的服务的具体信息，然后点击申请（Request）。 申请过程中会不断与你邮件联系。 一旦你获得了新的凭证信息，你需要更新你服务中的相关数值。
在Ovi商店发布你的应用
要使你的应用投入商业，你需要将其打包并发布到Ovi商店。 更多关于流程的信息参看打包和签名。 你也可以在Nokia论坛的产品分发页面找到更多关于发布的信息。
(no comments yet)