Android后台推送详解

运行环境

1. SDK支持Android 2.2 及以上版本的手机系统。

2. 手机必须要有网络（GPRS、3G或Wifi网络等）。

3. 手机可以没有SIM卡，但是可能导致部分功能缺失。

4. 手机可以不挂载SD卡，但会使部分功能无法正常工作。

说明

Appkey：预先分配的第三方应用ID。

AppSecret：认证密钥，预先协商后登记到双方服务端。

ClientID：用于标识客户端身份，由第三方客户端获取并保存到第三方服务端。

payload：透明数据（对用户透明），支持二进制格式（不支持转义字符），数据大小 不超过2k。个推系统不对消息内容进行解释，只负责将数据透传至第三 方客户端。

1.开发准备

1.1 注册账号并登记应用（必须）

【1】访问个推开放平台（http://dev.igetui.com），点击“免费注册”注册个推账户；

【2】按要求填入用户名、邮箱等基本信息，注册并激活账户；

【3】登录个推平台，按照提示登记应用，输入应用相关信息，点击“保存”创建您的应用。记录生成应用的AppKey/AppID/AppSecret信息，后续客户端集成过程中需要用到。

（应用标识请务必填写正确，如Android的标识为工程的package name，通常以com开始）

1.2获取SDK开发工具包（必须）

在网站下载开发工具包，包含客户端和服务端两部分：

（下载地址：http://www.igetui.com/download/android/SDK_OPEN.zip）

【1】客户端资料包含：

• 文档（手把手教你在Android上嵌入SDK）

• 需导入的资源（包含GetuiSdk-xx.jar和GetuiExt-xx.jar包、libgetuiext.so文件、layout文件夹等，您的应用需导入该jar库用于和SDK通信）

• 演示工程源码

• 真机测试包

【2】服务端资料包含：

• 文档（服务端API文档，详细指导如何调用接口）

• 需导入的资源

• php演示工程

2. 集成SDK（必须）

在Eclipse中打开您应用所在工程，并按照如下步骤集成

1. 将工具包中“个推Android平台SDK接入/客户端/需导入的资源”目录下的GetuiSdk-xxx.jar、GetuiExt-xxx.jar以及armeabi（如需arm-v7和x86的，点击下载：http://www.igetui.com/download/armeabi-v7a和x86.rar）文件夹复制到工程根目录下的libs文件夹中（若没有libs目录，则选中工程右键“New”->Folder->命名为“libs”）。

2. 右键单击工程，选择BuildPath中的ConfigureBuildPath...，选中Libraries，并通过AddJars...导入工程libs目录下的GetuiSdk-xxx.jar、GetuiExt-xxx.jar文件（最新的ADT工具会自动导入libs目录下的jar包，故该步骤可以省略。

3. 在您应用程序主Activity里导入PushManager如下所示：

import com.igexin.sdk.PushManager;

然后在您应用程序启动初始化阶段，初始化SDK：

PushManager.getInstance().initialize(this.getApplicationContext());

该方法必须在Activity或Service类内调用。一般情况下，可以在Activity的onCreate()方法中调用。不建议在Application继承类中调用。

为保证意外情况导致初始化失败，建议应用程序每次启动时都调用一次该初始化接口。

4. 将app_download_notification.xml、notification.xml、increment_popup_dialog.xml和

notification_inc.xml（在SDK/需导入的资源文件夹下）复制到工程res/layout/文件夹中。

5. 为了修改通知栏提示图标，请在res/drawable-hdpi/、res/drawable-mdpi/、res/drawable-ldpi/等

各分辨率资源目录下，放置相应尺寸的push.png图片。该通知栏提示图标显示位置如下：



6. 在AndroidManifest.xml 里添加SDK所需的服务声明和权限声明：

[1] 在Application标签内加入如下服务声明，注意黄色标注部分需进行相应的替换：

<!--个推SDK配置开始-->
<!--置的第三方参数属性-->
<meta-data
android:name="PUSH_APPKEY"
android:value="R03r2hiQI18UxbaFBZkRw"/>
<meta-data
android:name="PUSH_APPID"
android:value="etVyv7RHJ28BqN3KKCtKJ6"/>
<meta-data
android:name="PUSH_APPSECRET"
android:value="36IN4XOyHLAjma8E4d0BM2"/>
<meta-data
android:name="PUSH_GROUPID"
android:value=""/>
<!--配置SDK核心服务-->
<service
android:name="com.igexin.sdk.PushService"
android:exported="true"
android:label="NotificationCenter"
android:process=":pushservice">
</service>
<receiverandroid:name="com.igexin.sdk.PushReceiver">
<intent-filter>
<actionandroid:name="android.intent.action.BOOT_COMPLETED"/>
<actionandroid:name="android.net.conn.CONNECTIVITY_CHANGE"/>
<actionandroid:name="android.intent.action.USER_PRESENT"/>
<actionandroid:name="com.igexin.sdk.action.refreshls"/>
</intent-filter>
</receiver>
<receiverandroid:name="com.igexin.sdk.PushReceiver"
android:exported="false">
<intent-filter>
<actionandroid:name="com.igexin.sdk.action.pushmanager"/>
</intent-filter>
</receiver>
<activity
android:name="com.igexin.sdk.PushActivity"
android:excludeFromRecents="true"
android:exported="false"
android:process=":pushservice"
android:taskAffinity="com.igexin.sdk.PushActivityTask"
android:theme="@android:style/Theme.Translucent.NoTitleBar">
</activity>
<!--配置弹框activity-->
<activityandroid:name="com.igexin.getuiext.activity.GetuiExtActivity"
android:configChanges="orientation|keyboard|keyboardHidden"
android:excludeFromRecents="true"
android:process=":pushservice"
android:taskAffinity="android.task.myServicetask"
android:theme="@android:style/Theme.Translucent.NoTitleBar"
android:exported="false"/>
<receiverandroid:name="com.igexin.getuiext.service.PayloadReceiver"android:exported="false">
<intent-filter>
<!--这个com.igexin.sdk.action.7fjUl2Z3LH6xYy7NQK4ni4固定，不能修改-->
<actionandroid:name="com.igexin.sdk.action.7fjUl2Z3LH6xYy7NQK4ni4"/>
<!--android:name="com.igexin.sdk.action.第三方的appId"-->
<actionandroid:name="com.igexin.sdk.action.etVyv7RHJ28BqN3KKCtKJ6"/>
</intent-filter>
</receiver>
<serviceandroid:name="com.igexin.getuiext.service.GetuiExtService"
android:process=":pushservice"/>
<!--个推download模块配置-->
<serviceandroid:name="com.igexin.download.DownloadService"
android:process=":pushservice"/>
<receiver
android:name="com.igexin.download.DownloadReceiver">
<intent-filter>
<actionandroid:name="android.net.conn.CONNECTIVITY_CHANGE"/>
</intent-filter>
</receiver>
<provider
android:name="com.igexin.download.DownloadProvider"
android:process=":pushservice"
android:authorities="downloads.com.getui.demo"/>
<!--android:authorities="downloads.第三方包名"-->
<!--===========================================================================-->

[2] 在Application标签外加入需要的权限：

<uses-permissionandroid:name="android.permission.INTERNET"/>
<uses-permissionandroid:name="android.permission.READ_PHONE_STATE"/>
<uses-permissionandroid:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permissionandroid:name="android.permission.CHANGE_WIFI_STATE"/>
<uses-permissionandroid:name="android.permission.WAKE_LOCK"/>
<uses-permissionandroid:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
<uses-permissionandroid:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permissionandroid:name="android.permission.VIBRATE"/>
<uses-permissionandroid:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permissionandroid:name="getui.permission.GetuiService"/>
<uses-permissionandroid:name="android.permission.GET_TASKS"/>
<!--自定义权限-->
<permission
android:name="getui.permission.GetuiService"
android:protectionLevel="normal">
</permission>

3. 测试（必须）

运行您的工程，然后点击个推开放平台（dev.igetui.com）->应用管理->（对应应用）接入引导->④测试SDK的三个按钮，查看手机能否收到。



如果手机或模拟器收到通知，如图所示：恭喜您，SDK接入已经成功！

扩展功能

获取透传消息（可选）

如果要发送透传消息（如下图）您需要新建BroadcastReceiver子类。



该类的完成路径需要在AndroidManifest.xml 配置中用到，一般为：包名.类名。

比如示例代码中BroadcastReceiver子类包名：com.getui.demo，类名：PushDemoReceiver。

则其完整路径是：com.getui.demo.PushDemoReceiver，该路径将在AndroidManifest.xml 配置中用到。

BroadcastReceiver子类示例代码如下：

package com.getui.demo;
import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;
import android.os.Bundle;
import android.util.Log;
import com.igexin.sdk.PushConsts;
public class PushDemoReceiver
extends
BroadcastReceiver
{
@Override
public void onReceive(Context context, Intent intent) {
Bundle bundle = intent.getExtras();
Log.d("GetuiSdkDemo", "onReceive() action=" + bundle.getInt("action"));
switch (bundle.getInt(PushConsts.CMD_ACTION)) {
case PushConsts.GET_MSG_DATA:
// 获取透传（payload）数据
byte[] payload = bundle.getByteArray("payload");
if (payload != null)
{
String data = new String(payload);
Log.d("GetuiSdkDemo", "Got Payload:" + data);
// TODO:接收处理透传（payload）数据
}
break;
case PushConsts.GET_CLIENTID:
// 获取ClientID(CID)
String cid = bundle.getString("clientid")
Log.d("GetuiSdkDemo", "Got ClientID:" + cid);
// TODO:
/* 第三方应用需要将ClientID上传到第三方服务器，并且将当前用户帐号和ClientID进行关联，
以便以后通过用户帐号查找ClientID进行消息推送。有些情况下ClientID可能会发生变化，为保证获取最新的ClientID，
请应用程序在每次获取ClientID广播后，都能进行一次关联绑定 */
break;
case PushConsts.BIND_CELL_STATUS:
String cell = bundle.getString("cell");
Log.d("GetuiSdkDemo", "BIND_CELL_STATUS:" + cell);
if (GexinSdkDemoActivity.tLogView != null)
GexinSdkDemoActivity.tLogView.append("BIND_CELL_STATUS:" + cell + "\n");
break;
default:
break;
}
}
}

*具体代码可参照DEMO中的com.getui.demo.PushDemoReceiver类

[2]透传消息：

如下情况，发送的都是透传消息（payload）

在dev.igetui.com页面发送透传消息

服务端用pushMessageToSingle接口推送消息，同时模板类中含setTransmissionContent函数

用pushMessageToList或pushMessageToApp推送消息，同时模板类中含setTransmissionContent函数

注：透传消息和通知不同，通知收到后SDK会在通知栏展示并有铃声提醒。但对于透传，SDK只将消息传给第三方的客户端并不展示（需要您在如上BroadcastReceiver子类casePushConsts.GET_MSG_DATA:下写代码接收并决定如何处理）

比如社区论坛，当用户的帖子被回复后，可以发送数据给该用户提醒，提高活跃度。

如果需要发送透传消息，请在Application标签内加入如下声明

（您应用的AppID可以在 个推开放平台 -> 应用管理 -> 应用详情 看到）：

<receiverandroid:name="BroadcastReceiver子类完整路径">
<!--如下配置用于透传-->
<intent-filter>
<actionandroid:name="com.igexin.sdk.action.您应用的AppID"/>
</intent-filter>
</receiver>

[3]设置通知栏通知图标：

在个推开放平台->应用管理->（对应）应用设置->应用图标中设定。



[4]如图所示，在LogCat搜索“clientid”可以看到“clientidis...”，则意味则初始化SDK成功，恭喜你:-D

用户关系映射（可选）

要使用您自己的ID系统推送消息的话（例如向论坛中指定的帐号发送消息），您需要执行如下两步：

1. 将您应用的用户ID（UID）和ClientID建立映射绑定关系上传到您的服务器，ClientID可通过BroadcastReceiver子类bundle.getString(“clientid”)获取，详见上方接收广播消息

2. 将<UID,ClientID>映射表保存到您的服务端，推送时使用pushMessageToSingle等接口，详见《个推平台服务端接口文档》（文件位于：个推Android平台SDK接入/服务端/文档目录下）

如果开发者需要使用proguard进行混淆打包，请在proguard.cfg添加如下代码：

　　-dontwarncom.igexin.**
　　-keepclasscom.igexin.**{*;}

SDK接口

接口摘要
PushManager	SDK功能接口，以类方法形式提供给您的应用程序调用。 （注：每个应用程序只能初始化一次SDK，使用一个推送通道）。
Tag	标签结构，用于给用户打上标签（如可以用于精准化推送）

方法摘要（PushManager接口）
PushManager	getInstance() 获取当前PushManager对象的实例
void	initialize(Context context) 初始化推送服务
String	getVersion(Context context) 获取当前SDK的版本号
int	setTag(Context context, Tag[] tag) 为用户设置标签
boolean	setSilentTime(Context context,int beginHour,int duration) 设置静默时间，静默期间SDK将不再联网
void	stopService(Context context) 终止SDK的服务
boolean	isPushTurnOn(Context context) 检查SDK当前服务状态
void	turnOnPush(Context context) 开启push推送
void	turnOffPush(Context context) 关闭push推送
boolean	sendFeedbackMessage(Context context, String taskid, String messageid, int actionid) 上行第三方自定义回执actionid

方法摘要（Tag接口）
void	setName(String name) 设置当前Tag的Name值
String	getName() 获取当前Tag的name值

详细信息

PushManager

SDK功能接口，以类方法形式提供给您的应用程序调用。每个应用程序只能初始化一次SDK，使用一个推送通道。

getInstance

public static PushManager getInstance()

获取当前PushManager对象的实例，用来获取PayLoad（透传）数据等

指定者：

接口 PushManager 中的 getInstance

返回：

消息管理器PushManager的实例对象

initialize

public void initialize(Contextcontext)

初始化PushManager对象

指定者：

接口 PushManager 中的 initialize

参数：

context –

上下文

补充：

请保证在客户端程序每次启动时调用，以防止偶然因素导致初始化失败而无法推送

getVersion

public String getVersion(Contextcontext)

获取当前SDK的版本号

指定者：

接口 PushManager 中的 getVersion

参数：

context-

返回值：

SDK版本号

setTag

public int setTag(Contextcontext,Tag[]tag)

为用户设置标签

指定者：

接口 PushManager 中的 setTag

参数：

context–

tag-

标签，参见Tag

返回值：

0：成功

20001：tag数量过大（单次设置的tag数量不超过30）

20002：设置频率过快（频率限制每小时一次）

20003：标签重复

20004：aidl服务未绑定

20005：setTag异常

setSilentTime

public boolean setSilent Time(Contextcontext,intbeginHour,intduration)

设置静默时间，静默期间SDK将不再联网。

指定者：

接口 PushManager 中的 setSilentTime

参数：

context–

beginHour–

开始时间，设置范围在0-23小时之间

Duration–

持续时间，设置范围在0-23小时之间。持续时间为0则不静默。

返回值：

true：设置成功

false：设置失败

举例：

比如设置beginHour为15，Duration为10小时，则在15:00-次日1:00这10个小时内SDK将不会联网。

stopService

public void stopService(Contextcontext)

完全终止SDK的服务

指定者：

接口 PushManager 中的 stopService

参数：

context–

isPushTurnedOn

public boolean isPushTurnedOn(Contextcontext)

获取当前SDK的服务状态

指定者：

接口 PushManager 中的 isPushTurnedOn

参数：

context–

返回值：

true：当前推送已打开

false：当前推送已关闭

turnOnPush

public void turnOnPush(Contextcontext)

开启Push推送

指定者：

接口 PushManager 中的 turnOnPush

参数：

context–

补充：

优先级高于stopService，如果当前是stopService状态，调用turnOnPush之后仍然可以正常推送。

turnOffPush

public void turnOffPush(Contextcontext)

关闭Push推送

指定者：

接口 PushManager 中的 turnOffPush

参数：

context–

sendFeedbackMessage

public boolean sendFeedbackMessage(Contextcontext,Stringtaskid,Stringmessageid,intactionid)

上行第三方自定义回执actionid

指定者：

接口 PushManager 中的 sendFeedbackMessage

参数：

context–

taskid–

下发任务的任务ID。

messageid–

下发任务的消息ID。

actionid–

用户自定义的actionid，int类型，取值90001-90999。

返回值：

true：上行成功。

false：上行失败；taskid为空，或者messageid为空，或者actionid不在取值范围以内。

Tag

标签结构

setName

public void setName(Stringname)

设置当前Tag的Name值

指定者：

接口 Tag 中的 setName

参数：

需要传入的Tag名，只支持以下：中文、英文字母（大小写）、数字、加号（“+”）、减号（“-”）、星号（“*”）、下划线（“_”）、冒号（“:”）以及空格

getName

public String getName()

获取当前Tag的name值

指定者：

接口 Tag 中的 getName

返回值：

当前Tag名字