云推送

服务概述

云推送(Push)是新浪云开发的协助开发者推送手机通知的服务,目前支持iOS和Android系统的推送。

iOS版本介绍

服务说明

开发者通过编写代码调用API接口(或直接通过新浪云提供的页面)推送消息,消息先存到新浪云,再由新浪云的推送服务发送到苹果的推送服务器(APNs),最后由APNs投递到用户的手机。请参照下图:

../../_images/pushApple.png

使用推送服务,首先请在新浪云应用的“服务管理”列表中找到“云推送”服务页面,在“推送设置”页面上传证书。证书的生成请参考苹果官方文档。证书上传成功后就可以通过调用新浪云云推送服务接口(或“云推送”页面“推送消息”页)推送手机通知了。

注解

为提高苹果推送的及时性和成功率,请开发者注意以下几点:

  1. 请注意证书的类型,正确选择开发环境和正式环境。
  2. 请注意证书的过期时间。
  3. push函数调用成功,只代表消息已推送到新浪云服务器,并不代表成功推送到苹果服务器。(“推送统计”展示的推送成功数代表成功推送到苹果服务器)。
  4. 如需查看推送成功率(该数据会有十分钟左右延迟),可通过“推送统计”查看,也可以使用getinfo函数查看(目前该接口只提供当天的数据)。
  5. 如需要查看具体失败的原因,可通过“日志中心”的云推送页查看。

服务限制

单app最大上传证书数 10

iOS API使用手册

点击查看

使用示例

下面使用代码来说明云推送iOS服务的调用方式。

<?php

$cert_id = 1;
$device_token = "xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx xxxxxxxx";
$message = "hello world";

//这个是简单的例子,更复杂的消息格式请查看苹果官方文档
$body = array(
    'aps' => array( 'alert' => $message , 'badge' => 1, 'sound' => 'in.caf')
);
$apns = new SaeAPNS();
//push消息到新浪云推送服务器
$result = $apns->push( $cert_id , $body , $device_token );

if( $result && is_array($result) ){
    echo '发送成功';
    var_dump( $result );
} else {
    echo '发送失败';
    var_dump($apns->errno(), $apns->errmsg());
}

//查看消息发送的汇总信息,返回值包括当天发送成功的消息数,以及因各类原因发送失败的消息数。
$result = $apns->getInfo($cert_id);
if ($result === false) {
    echo "getInfo失败";
    var_dump($apns->errno(), $apns->errmsg());
} else {
    echo "getInfo成功";
    var_dump($result);
}

?>

Android版本介绍

服务说明

开发者通过编写代码调用API接口(或直接通过新浪云提供的页面)推送消息,消息先存到新浪云,再由新浪云的推送服务投递到用户的手机。请参照下图:

../../_images/pushAndroid.png

使用推送服务,首先需要在新浪云应用的“服务管理”列表中找到“云推送”服务页面,在“推送设置”页面申请AppID。

Android Push Service用AppID来标识应用。申请完AppID后,即可参考 Android SDK 说明 在Android App中嵌入新浪云的SDK了。

App开发完成后,可以使用新浪云云推送服务接口推送手机通知。

服务限制

单app可申请的AppID 1
离线消息存储条数 最后5条
离线消息有效期 12小时
最大消息长度 4M

Android SDK 说明

概述

新浪云 Android Push SDK以Jar包的形式提供,方便开发者使用,对外的调用类只有一个PushManager,通过这个类可以打开、关闭、刷新Push的通道。Push通道以TCP长连接的形式存在。

集成SDK

云推送Android SDK 下载新浪云云推送Android的SDK并解压。

在Eclipse中打开需要使用云推送服务的工程,按照如下步骤集成。

在工程根目录下的libs文件夹中,导入SDK里的SinaPush_{version}_SAE_release.jar包和最新的android-support-v{version}.jar 包,若没有libs目录,则选中工程,右键new->folder,命名为libs。

在应用的 AndroidManifest.xml 中添加相关权限

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
<uses-permission android:name="android.permission.WRITE_SMS" />
<uses-permission android:name="android.permission.READ_SMS" />
<uses-permission android:name="android.permission.GET_TASKS" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="yourPackageName.permission.SINA_PUSH" />

<!-- 添加 SinaPushSDK 自定义的权限 -->
<permission
android:name=" yourPackageName.permission.SINA_PUSH"
android:protectionLevel="normal" />

在应用的AndroidManifest.xml中配置服务

<!--
声明使用 SinaPushSDK 必须启动的服务
com.sina.push.service.SinaPushService注意:需要有 android:permission="
yourPackageName.permission.SINA_PUSH"
-->
<service
android:name="com.sina.push.service.SinaPushService"
android:label="PushDataCenter"
android:permission="yourPackageName.permission.SINA_PUSH"
android:process=":remote" >
<intent-filter>
<!--
SinaPushSDK service action 命名规则
sina.push.action.service.APPID
注意必须为: sina.push.action.service. + APPID
-->
<action android:name="sina.push.action.service.1004" />
<category android:name="android.category.DEFAULT" />
</intent-filter>
</service>
<!--
声明使用 SinaPushSDK 必须注册的广播事件
-->
<receiver android:name="com.sina.push.receiver.PushSDKReceiver" >
<intent-filter>
<action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
<action android:name="android.intent.action.BOOT_COMPLETED" />
</intent-filter>
</receiver>
<!--
声明使用 SinaPushSDK 接收透传消息的广播事件
-->
<receiver android:name=".SDKMsgReceiver" >
<intent-filter>
<action android:name="com.sina.push.msg.broadcast.1004" /></intent-filter>
</receiver>
<provider android:name="com.sina.push.datacenter.PushProvider"
android:process=":remote"
android:multiprocess="false"
android:authorities="com.sina.push.pushprovider.1004"/>
<meta-data android:name="sinapush_appid" android:value="1004" />

注解

上文Demo中的1004,应替换为自己应用的AppID,AppID需要从新浪云的服务页面申请。

在调用所有接口前,必须先进行初始化,且初始化只需要调用一次。

PushManager manager = PushManager.getInstance(getApplicationContext());

接收 Push 消息

消息分类

Push消息分为两类,一类是SDK处理的消息,一类是透传给App处理的消息。

  1. SDK处理的消息:Android Push SDK 收到消息后,SDK直接处理,不会透传给App。
  2. 透传给App的消息:Android Push SDK 收到消息后,直接封装,透传给App处理。如果想将消息透传给App,需要在推送消息时,添加extra字段。如:使用示例 中push时添加的 $extra 参数。

注解

如果想由应用自己来处理、展示 push 消息,那么必须由 Server 端在消息中 extra 字段内添加 json 格式的信息:

handle_by_app: 1 为 app 处理, 0 为 SDK 处理, 默认为 0。

接收Push消息

Push 的消息类型

类型 说明 消息实体
MSG_TYPE_MPS_PUSH_DATA Push 消息 PushDataPacket
MSG_TYPE_ACTION_SWITCH_CHANNEL 通道打开消息 ActionResult
MSG_TYPE_SAE_DATA Aid 消息 String
MSG_CHANNEL_HAS_BEEN_BUILDED 通道打开消息

注解

aid是推送服务的设备标识,推送消息时,会要求提供aid参数:

  1. 设备的aid不是永久不变的,设备长时间未连接到服务器,aid标识会被服务器端删除,再次连接时会重新分配aid。
  2. 清除App数据也会导致aid改变。

Demo

public void onReceive(Context context, Intent intent) {
    // TODO Auto-generated method stub
    int msg_type = intent.getIntExtra(MPSConsts.CMD_ACTION, -1);
    switch(msg_type){
    case MPSConsts.MSG_TYPE_MPS_PUSH_DATA:
        PushDataPacket packet = intent.getParcelableExtra(MPSConsts.KEY_MSG_MPS_PUSH_DATA);
        Toast.makeText(context, "onPush data: " + packet.getSrcJson(),
        Toast.LENGTH_LONG).show();
        break;
    case MPSConsts.MSG_TYPE_UPLOAD_BUSINESS_ERROR:
        break;
    case MPSConsts.MSG_CHANNEL_HAS_BEEN_BUILDED:
        System.out.println("MPSConsts.MSG_CHANNEL_HAS_BEEN_BUILDED!");
        Toast.makeText(context, "MSG_CHANNEL_HAS_BEEN_BUILDED", Toast.LENGTH_LONG).show();
        break;
    case MPSConsts.MSG_TYPE_SAE_DATA:
        String aid = intent.getStringExtra(MPSConsts.KEY_MSG_SAE_DATA);
        LogUtil.debug("SDKMsgReceiver aid ===========" + aid);
        Toast.makeText(context, aid, Toast.LENGTH_LONG).show();
        break;
    }
}

跳转到具体页面

1. 跳转到某个应用的页面: SDK 收到 push 消息后会发出一个 notification 或是弹出一个 dialog。当用户点击notification 或对话框上的按钮时,会跳转到相应的页面。例如掌中新浪,收到了一个 push下来的新闻消息,展示为 notification,点击后跳转到显示新闻的 activity 中。要想完成上述功能,需要在 push 消息中 acts 字段的参数中包含该应用的包名和 activity 的类名。

动作名/动作 ID:2

参数 1:包名

参数 2:完整类名

“acts”: [“2,com.sina.news,com.sina.news.ui.NewContentActivity”],

2. 跳转到浏览器: SDK 收到消息后如果想跳转到浏览器,需要在 push 消息中 acts 字段的参数中包含 url地址。

动作名/动作 ID:4

参数 1:url 地址

“acts”: [“4,http://www.sina.com”],

3. 通过 Scheme 跳转: 通过 Scheme 跳转到某个应用的 activity 中。

动作名/动作 ID:5

参数 1:scheme

“acts”: [“5,sinaweibo://sendweibo”],

Android SDK API说明

public void initPushChannel(String... params)

打开特定类型的Push通道,准备接收Push消息

注解

在通道的准备过程中,调用功能接口可能会失败, 请先处理initPushChannel(string)的执行结果。

参数:
  • appID (String) – 应用程序的唯一序号(由 新浪云 服务面板申请的AppID)
  • channelID (String) – 通道编号, 由 新浪云 指定, 同 appID
  • wm (String) – 暂无含义,填入 ‘100’
  • from (String) – 暂无含义,填入 ‘100’
public void close()

关闭当前打开的通道,停止接收Push消息, 直到再次调用initPushChannel()。

public void refreshConnection()

刷新连接,如果连接断开,则立即进行重连。

Android API使用手册

点击查看

使用示例

下面使用代码来说明云推送Android服务的调用方式。

<?php

$appid = 20001;
$token = 'BYfkQcUYULUB';
$title = 'title';
$msg = 'hello wolrd';
$acts = "[\"2,sina.Apns,sina.Apns.MainActivity\"]";
$extra = array(
    'handle_by_app'=>'0'
);

$adpns = new SaeADPNS();
//appid 是应用的标识,从新浪云的推送服务页面申请
//token 是SDK通道标识,从SDK的onPush中获取
$result = $adpns->push($appid, $token, $title, $msg, $acts, $extra);
if ($result && is_array($result)) {
    echo '发送成功!';
    var_dump($result);
} else {
    echo '发送失败。';
    var_dump($apns->errno(), $apns->errmsg());
}

?>