运行环境
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名字