Android版本介绍
=================

服务说明
------------------------------

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

.. image:: /images/pushAndroid.png
    :height: 175px

使用推送服务，首先需要在新浪云应用的“服务管理”列表中找到“云推送”服务页面，在“推送设置”页面申请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
~~~~~~~~~~

从 :ref:`push-android-sdk` 下载新浪云云推送Android的SDK并解压。

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

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

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

.. code-block:: 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中配置服务

.. code-block:: 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" />

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

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

.. code-block:: java

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

接收 Push 消息
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**消息分类**

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

1. SDK处理的消息：Android Push SDK 收到消息后，SDK直接处理，不会透传给App。
2. 透传给App的消息：Android Push SDK 收到消息后，直接封装，透传给App处理。如果想将消息透传给App，需要在推送消息时，添加extra字段。如：:ref:`Android-api-use` 中push时添加的 `$extra` 参数。

.. note:: 如果想由应用自己来处理、展示 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    通道打开消息   无
=============================== ============== ===================

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

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

Demo

.. code-block:: java

    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"],

.. **点击率统计**

.. 如果需要统计 notification 的点击率,需要额外配置,在唤起的 Activity 页面 onCreate 添加如下代码:

.. .. code-block:: java

..     if (getIntent() != null) {
..         manager.sendClickFeedBack (getIntent());
..     }


Android SDK API说明
~~~~~~~~~~~~~~~~~~~~~

.. java:package:: PushManager

.. java:method:: public void initPushChannel(String... params)
    :noindex:

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

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

    :param String appID: 应用程序的唯一序号（由 新浪云 服务面板申请的AppID）
    :param String channelID: 通道编号, 由 新浪云 指定, 同 appID
    :param String wm: 暂无含义,填入 ‘100’
    :param String from: 暂无含义,填入 ‘100’


.. java:method:: public void close()
    :noindex:

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


.. java:method:: public void refreshConnection()
    :noindex:

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