Android后台推送详解

淩亂°似流年 2022-08-20 12:24 650阅读 0赞

## 运行环境 ##

1. SDK支持Android 2.2 及以上版本的手机系统。  
2. 手机必须要有网络（GPRS、3G或Wifi网络等）。  
3. 手机可以没有SIM卡，但是可能导致部分功能缺失。  
4. 手机可以不挂载SD卡，但会使部分功能无法正常工作。  
![android-sdk-1][]

### 说明 ###

**Appkey：**预先分配的第三方应用ID。  
**AppSecret：**认证密钥，预先协商后登记到双方服务端。  
**ClientID：**用于标识客户端身份，由第三方客户端获取并保存到第三方服务端。  
**payload：**透明数据（对用户透明），支持二进制格式（不支持转义字符），数据大小 不超过2k。个推系统不对消息内容进行解释，只负责将数据透传至第三 方客户端。

## 1.开发准备 ##

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

【1】访问个推开放平台（[http://dev.igetui.com][http_dev.igetui.com]），点击“免费注册”注册个推账户；  
【2】按要求填入用户名、邮箱等基本信息，注册并激活账户；  
【3】登录个推平台，按照提示登记应用，输入应用相关信息，点击“保存”创建您的应用。记录生成应用的AppKey/AppID/AppSecret信息，后续客户端集成过程中需要用到。

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

![android-sdk-2][]

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

在网站下载开发工具包，包含客户端和服务端两部分：  
（下载地址：[http://www.igetui.com/download/android/SDK\_OPEN.zip][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][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图片。该通知栏提示图标显示位置如下：

![android-sdk-3][]

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

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

<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=""/>
    
    <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>
    
    <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>
    
    <actionandroid:name="com.igexin.sdk.action.7fjUl2Z3LH6xYy7NQK4ni4"/>
    
    <actionandroid:name="com.igexin.sdk.action.etVyv7RHJ28BqN3KKCtKJ6"/>
    </intent-filter>
    </receiver>
    <serviceandroid:name="com.igexin.getuiext.service.GetuiExtService"
    android:process=":pushservice"/>
    
    <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"/>

\[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的三个按钮，查看手机能否收到。

![android-sdk-4][]

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

![android-sdk-5][]

## 扩展功能 ##

### 获取透传消息（可选） ###

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

![android-sdk-6][]

该类的完成路径需要在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\]设置通知栏通知图标：

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

![android-sdk-7][]

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

![android-sdk-8][]

### 用户关系映射（可选） ###

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

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

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

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

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

## SDK接口 ##

<table style="border-collapse:collapse; border-spacing:0px; width:714px; border:1px solid rgb(219,219,219); margin:15px 0px; color:rgb(84,84,84); font-family:微软雅黑,黑体,宋体; font-size:14px; height:720px; background-color:rgb(250,250,250)"> 
 <tbody> 
  <tr> 
   <td colspan="2" style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219); text-align:center"> <strong>方法摘要（PushManager接口）</strong></td> 
  </tr> 
  <tr> 
   <td style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219)"> PushManager</td> 
   <td style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219)"> getInstance()<br> 获取当前PushManager对象的实例</td> 
  </tr> 
  <tr> 
   <td style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219)"> void</td> 
   <td style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219)"> initialize(Context context)<br> 初始化推送服务</td> 
  </tr> 
  <tr> 
   <td style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219)"> String</td> 
   <td style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219)"> getVersion(Context context)<br> 获取当前SDK的版本号</td> 
  </tr> 
  <tr> 
   <td style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219)"> int</td> 
   <td style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219)"> setTag(Context context, Tag[] tag)<br> 为用户设置标签</td> 
  </tr> 
  <tr> 
   <td style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219)"> boolean</td> 
   <td style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219)"> setSilentTime(Context context,int beginHour,int duration)<br> 设置静默时间，静默期间SDK将不再联网</td> 
  </tr> 
  <tr> 
   <td style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219)"> void</td> 
   <td style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219)"> stopService(Context context)<br> 终止SDK的服务</td> 
  </tr> 
  <tr> 
   <td style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219)"> boolean</td> 
   <td style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219)"> isPushTurnOn(Context context)<br> 检查SDK当前服务状态</td> 
  </tr> 
  <tr> 
   <td style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219)"> void</td> 
   <td style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219)"> turnOnPush(Context context)<br> 开启push推送</td> 
  </tr> 
  <tr> 
   <td style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219)"> void</td> 
   <td style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219)"> turnOffPush(Context context)<br> 关闭push推送</td> 
  </tr> 
  <tr> 
   <td style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219)"> boolean</td> 
   <td style="margin:0px; padding:10px 5px; border:1px solid rgb(219,219,219)"> sendFeedbackMessage(Context context, String taskid, String messageid, int actionid)<br> 上行第三方自定义回执actionid</td> 
  </tr> 
 </tbody> 
</table>

### 详细信息 ###

#### 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 **turnOnPus**h(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名字

[android-sdk-1]: /images/20220731/8dafd341b05b437d96fae5cc72933d77.png
[http_dev.igetui.com]: http://dev.igetui.com/
[android-sdk-2]: /images/20220731/314354fe3b90491ba9259add90e3cd3a.png
[http_www.igetui.com_download_android_SDK_OPEN.zip]: http://www.igetui.com/download/android/SDK_OPEN.zip
[http_www.igetui.com_download_armeabi-v7a_x86.rar]: http://www.igetui.com/download/armeabi-v7a%E5%92%8Cx86.rar
[android-sdk-3]: /images/20220731/e34083f27cba4dce81522de09d578879.png
[android-sdk-4]: /images/20220731/77328f73e35443099bc36e9c202b9fae.png
[android-sdk-5]: /images/20220731/e0e4d8717eda4b829809b6e11edf6ec3.png
[android-sdk-6]: /images/20220731/b01c6c104c6e47e8ad95b697b86a0c71.png
[android-sdk-7]: /images/20220731/2ed8dfec428e4c90993d19b5fa031066.png
[android-sdk-8]: /images/20220731/c7d25a37a43b44848d7e8b33acbe4204.png