个推平台客户端SDK接入文档
（JAR模式）
编号: GEXIN_ANDROID_SDK_JAR 版本: GEXIN_ANDROID_SDK_JAR V1.3.8
个信互动（北京）网络科技有限公司
2013年11月
1 / 22
个信互动（北京）网络科技有限公司 [普通]
目录
开发准备........................................................................................................................................... 4
1. 注册账号并登记应用（必须） ....................................................................................... 4 2. 获取SDK开发工具包（必须） ...................................................................................... 4 集成SDK（必须） ........................................................................................................................... 5 测试（必须） ................................................................................................................................... 9 扩展功能......................................................................................................................................... 10
获取透传消息（可选） ......................................................................................................... 10 用户关系映射（可选） ......................................................................................................... 15 SDK接口 ......................................................................................................................................... 16
MessageManager .................................................................................................................... 18
getInstance ..................................................................................................................... 18 initialize .......................................................................................................................... 18 getNetstat ........................................................................................................................ 18 feedbackAction .............................................................................................................. 19 getVersion ...................................................................................................................... 19 setTag .............................................................................................................................. 20 setSilentTime.................................................................................................................. 20 stopService ..................................................................................................................... 20 GexinSdkNetstat ...................................................................................................................... 21
inboundBytes ................................................................................................................. 21 outboundBytes ............................................................................................................... 21 Tag ........................................................................................................................................... 21
setName .......................................................................................................................... 22 getName ......................................................................................................................... 22
2 / 22
个信互动（北京）网络科技有限公司 [普通]
运行环境
1. SDK支持Android 1.6及以上版本的手机系统 2. 手机必须要有网络（GPRS、3G或Wifi网络等） 3. 手机可以没有SIM卡，但是可能导致部分功能缺失
4. 手机可以不挂载SD卡，但会使部分功能无法正常工作。
推送服务框架
维护 说明： Appkey： 预先分配的第三方应用ID。 AppSecret： 认证密钥，预先协商后登记到双方服务端。 ClientID： 用于标识客户端身份，由第三方客户端获取并保存到第三方服务端。 payload： 透明数据（对用户透明），支持二进制格式（不支持转义字符），数据大小 不超过2k。个信系统不对消息内容进行解释，只负责将数据透传至第三 方客户端。 3 / 22 个信互动（北京）网络科技有限公司 [普通] 开发准备 1. 注册账号并登记应用（必须） [1] 访问个推开放平台（http://dev.igetui.com），点击“免费注册”注册个推账户 [2] 按要求填入用户名、邮箱等基本信息，注册并激活账户 [3] 登录个推平台，按照提示登记应用，输入应用相关信息，点击“保存”创建您的应用 （应用标识请务必填写正确，如Android的标识为工程的package name，通常以com开始） 2. 获取SDK开发工具包（必须） 在网站下载开发工具包，包含客户端和服务端两部分： （下载地址：http://www.igetui.com/download/android/SDK_OPEN.zip） 客户端包含： 4 / 22 个信互动（北京）网络科技有限公司 [普通] • 文档（手把手教你在Android上嵌入SDK） • 需导入的资源（包含GexinSdk.jar和IncrementSDK.jar包、armeabi \\libincrement.so文件、layout文件夹等，您的应用需导入该jar库用于和SDK通信） • 演示工程源码 • 真机测试包 服务端包含： • 文档（服务端API文档，详细指导如何调用接口） • 需导入的资源 • php演示工程 集成SDK（必须） 在Eclipse中打开您应用所在工程，并按照如下步骤集成 1. 将工具包中“个推Android平台SDK接入/客户端/需导入的资源”目录下的 GexinSdk.jar、IncrementSDK.jar以及armeabi文件夹(包含libincrement.so文件)复制到工程根目录下的libs文件夹中 （若没有libs目录，则选中工程右键“New”->Folder->命名为“libs”） 2. 右键单击工程，选择Build Path中的Configure Build Path...，选中Libraries，并 通过Add Jars...导入工程libs目录下的GexinSdk.jar和IncrementSDK.jar文件 （最新的ADT工具会自动导入libs目录下的jar包，故该步骤可以省略） 3. 在您应用程序主Activity里导入MessageManager如下所示： import com.igexin.slavesdk.MessageManager; 然后在您应用程序启动初始化阶段，初始化SDK： MessageManager.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图片。该通知栏提示图 5 / 22 个信互动（北京）网络科技有限公司 [普通] 标显示位置如下： 6. 在AndroidManifest.xml 里添加SDK所需的服务声明和权限声明： [1] 在Application标签内加入如下服务声明，注意红色标注部分需进行相应的替换： /> android:theme=\"@android:style/Theme.Translucent.NoTitleBar\" android:taskAffinity=\"android.task.GexinSdkActivityTask\" android:excludeFromRecents=\"true\" android:exported=\"false\"> com.igexin.action.popupact.第三方的包名 个信互动（北京）网络科技有限公司 [普通] android:process=\":pushservice\" android:exported=\"true\"> android:name=\"sdk.download.DownloadProvider\"/> 7 / 22 个信互动（北京）网络科技有限公司 [普通] android:taskAffinity=\"android.task.myServicetask\" android:theme=\"@android:style/Theme.Translucent.NoTitleBar\" android:exported=\"false\" /> [2] 在Application标签外加入需要的权限： 8 / 22 个信互动（北京）网络科技有限公司 [普通] [3] 在您应用主Activity标签内加入android:launchMode=\"singleTop\"。例如，您的主activity名为MainActivity，则需要增加如下红字提示的内容。 测试（必须） 运行您的工程，然后点击个推开放平台（dev.igetui.com） -> 应用管理 -> （对应应用）接入引导 -> ④ 测试SDK 的三个按钮，查看手机能否收到。 如果手机或模拟器收到通知，如图所示：恭喜您，SDK接入已经成功！ 9 / 22 个信互动（北京）网络科技有限公司 [普通] 扩展功能 获取透传消息（可选） 如果要发送透传消息（如下图）您需要新建BroadcastReceiver子类。 10 / 22 个信互动（北京）网络科技有限公司 [普通] 该类的完成路径需要在AndroidManifest.xml 配置中用到，一般为：包名.类名。 比如示例代码中BroadcastReceiver子类包名：com.sdk.demo，类名：SdkMsgReceiver。则其完整路径是：com.sdk.demo.SdkMsgReceiver，该路径将在AndroidManifest.xml 配置中用到。 BroadcastReceiver子类示例代码如下： package com.sdk.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.Consts; public class SdkMsgReceiver extends BroadcastReceiver { 11 / 22 个信互动（北京）网络科技有限公司 [普通] @Override public void onReceive(Context context, Intent intent) { } } } Log.d(\"GexinSdkDemo\ GexinSdkDemoActivity.tLogView.append(\"BIND_CELL_STATUS:\" + break; break; if (GexinSdkDemoActivity.tLogView != null) break; String cell = bundle.getString(\"cell\"); case Consts.BIND_CELL_STATUS: Bundle bundle = intent.getExtras(); Log.d(\"GexinSdkDemo\ \"onReceive() action=\" + bundle.getInt(\"action\")); switch (bundle.getInt(Consts.CMD_ACTION)) { case Consts.GET_MSG_DATA: // 获取透传（payload）数据 byte[] payload = bundle.getByteArray(\"payload\"); if (payload != null) { } break; String data = new String(payload); Log.d(\"GexinSdkDemo\// TODO:接收处理透传（payload）数据 case Consts.GET_CLIENTID: // 获取ClientID(CID) String cid = bundle.getString(\"clientid\"); Log.d(\"GexinSdkDemo\// TODO: /* 第三方应用需要将ClientID上传到第三方服务器，并且将当前用户帐号和有些情况下ClientID可能会发生变化，为保证获取最新的ClientID，请应用程序 ClientID进行关联，以便以后通过用户帐号查找ClientID进行消息推送 在每次获取ClientID广播后，都能进行一次关联绑定 */ cell + \"\\n\"); default: *具体代码可参照DEMO中的com.igexin.demo.SdkMsgReceiver类 12 / 22 个信互动（北京）网络科技有限公司 [普通] [2]透传消息： 如下情况，发送的都是透传消息（payload） 在dev.igetui.com页面发送透传消息 服务端用pushMessageToSingle接口推送消息，同时模板类中含 setTransmissionContent函数 用pushMessageToList或pushMessageToApp推送消息，同时模板类中含 setTransmissionContent函数 注：透传消息和通知不同，通知收到后SDK会在通知栏展示并有铃声提醒。但对于透传，SDK只将消息传给第三方的客户端并不展示（需要您在如上BroadcastReceiver子类case Consts.GET_MSG_DATA:下写代码接收并决定如何处理） 比如社区论坛，当用户的帖子被回复后，可以发送数据给该用户提醒，提高活跃度。 如果需要发送透传消息，请在Application标签内加入如下声明 （您应用的AppID可以在 个推开放平台 -> 应用管理 -> 应用详情 看到）： [3]设置通知栏通知图标： 在个推开放平台 -> 应用管理 -> （对应）应用设置 -> 应用图标 中设定。 13 / 22 个信互动（北京）网络科技有限公司 [普通] [4]如图所示，在LogCat搜索“clientid”可以看到“clientid is ...”，则意味则初 始化SDK成功，恭喜你:-D 14 / 22 个信互动（北京）网络科技有限公司 [普通] 用户关系映射（可选） 要使用您自己的ID系统推送消息的话（例如向论坛中指定的帐号发送消息），您需要执行如下两步： 1. 将 您应用的用户ID（UID）和ClientID建立映射绑定关系上传到您的服务器，ClientID 可通过BroadcastReceiver子类bundle.getString(“clientid”) 获取，详见上方接收广播消息 2. 将 口，详见《个推平台服务端接口文档》 （文件位于：个推Android平台SDK接入/服务端/文档 目录下） 3. 如果开发者需要使用proguard进行混淆打包，请在proguard.cfg 添加如下代码： -dontwarn com.igexin.** -dontwarn sdk.** -keep class com.igexin.** { *; } -keep class sdk.** { *; } 15 / 22 个信互动（北京）网络科技有限公司 [普通] SDK接口 接口摘要 MessageManager GexinSdkNetstat Tag SDK功能接口，以类方法形式提供给您的应用程序调用。 （注：每个应用程序只能初始化一次SDK，使用一个推送通道）。 从getNetstat获取的网络信息结构，包括流量信息，网络状态等 标签结构，用于给用户打上标签（如可以用于精准化推送） 16 / 22 个信互动（北京）网络科技有限公司 [普通] 方法摘要（GexinSdkNetStat接口） inboundBytes long 从网络接收到的字节数统计 long 方法摘要（Tag接口） void String setName(String name) 设置当前Tag的Name值 getName() 获取当前Tag的name值 outboundBytes 向网络发送的字节数统计 17 / 22 个信互动（北京）网络科技有限公司 [普通] 方法详细信息 MessageManager SDK功能接口，以类方法形式提供给您的应用程序调用。每个应用程序只能初始化一次SDK，使用一个推送通道。 getInstance public static MessageManager getInstance() 获取当前MessageManager对象的实例，用来获取PayLoad（透传）数据等 指定者： 接口 MessageManager 中的 getInstance 返回： 消息管理器MessageManager的实例对象 initialize public void initialize(Context context) 初始化MessageManager对象 指定者： 接口 MessageManager 中的 initialize 参数： context – 上下文 补充： 请保证在客户端程序每次启动时调用，以防止偶然因素导致初始化失败而无法推送 getNetstat public boolean getNetstat(Context context, GexinSdkNetstat netstat) 获取网络流量数据（上传、下载数据字节数） 指定者： 接口 MessageManager 中的 getNetstat 参数： context – 18 / 22 个信互动（北京）网络科技有限公司 [普通] netstat – 网络流量等。参见 GexinSdkNetstat 返回值： 如果获取成功，返回true feedbackAction public boolean feedbackAction(Context context, String payloadID, int actionID, String result) 获取反馈动作执行结果 指定者： 接口MessageManager中的feedbackAction 参数： context – payloadID – 要反馈消息的payloadid actionID - 动作代表序列 result – 可选值： ok：动作已执行 failed：动作执行失败 discarded：动作被忽略（如当push消息被剃重时） installed:推广的软件已经被安装 返回值： 获取成功返回true getVersion public String getVersion(Context context) 获取当前SDK的版本号 指定者： 接口MessageManager中的getVersion 参数： context - 返回值： SDK版本号 19 / 22 个信互动（北京）网络科技有限公司 [普通] setTag public int setTag(Context context, Tag[] tag) 设置标签 指定者： 接口MessageManager中的setTag 参数： context – tag - 标签，参见Tag 返回值： 0：成功 20001：tag数量过大（单次设置的tag数量不超过30） 20002：设置频率过快（频率限制每小时一次） 20003：标签重复 20004：aidl服务未绑定 20005：setTag异常 setSilentTime public boolean setSilentTime(Context context,int beginHour,int duration) 设置静默时间，静默期间SDK将不再联网。 指定者： 接口MessageManager中的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(Context context) 20 / 22 个信互动（北京）网络科技有限公司 [普通] 完全终止SDK的服务 指定者： 接口MessageManager中的stopService 参数： context – GexinSdkNetstat 从getNetstat获取的网络信息结构，包括流量信息，网络状态等 inboundBytes public static long inboundBytes 从网络接收到的字节数统计 指定者： 接口GexinSdkNetstat中的inboundBytes 返回值： 从SDK启动开始从网络接收到的总字节数（包括WIFI和移动网络） outboundBytes public static long outboundBytes 向网络发送的字节数统计 指定者： 接口GexinSdkNetstat中的outboundBytes 返回值： 从SDK启动开始向网络发送的总字节数（包括WIFI和移动网络） Tag 标签结构 21 / 22 个信互动（北京）网络科技有限公司 [普通] setName public void setName (String name) 设置当前Tag的Name值 指定者： 接口Tag中的setName 参数： 需要传入的Tag名，只支持以下：中文、英文字母（大小写）、数字、加号（“+”）、 减号（“-”）、星号（“*”）、下划线（“_”）、冒号（“:”）以及空格 getName public String getName() 获取当前Tag的name值 指定者： 接口Tag中的getName 返回值： 当前Tag名字 22 / 22 因篇幅问题不能全部显示，请点此查看更多更全内容