文档中心 登录/注册 SDK下载 个推学堂

当前位置：个推文档 > 客户端 > Android > 集成指南

集成指南

集成指南

前言   

！集成多厂商，实现安卓离线推送，快速提高消息到达率

  • 本文档介绍 Android Studio 开发环境下基于 Maven 方式集成的步骤。
  • 本文档适用 SDK 版本：3.1.2.0 及以后

  • 本文默认读者已经具有基础的 Android 知识，以及项目工程结构如下：

    Getui_SDK_Demo_AS_official/
    |- app/ （项目主模块）
    |    |- libs/ （第三方库）
    |    |- src/ （代码目录）
    |    |- build.gradle （模块级 gradle 文件）
    |- gradle/
    |- build.gradle （顶层 gradle 文件）
    |- settings.gradle
    | ......

    注：其中 “......” 表示省略其他与本教程无关的内容，以下 “......” 表示相同意义，不再重复说明。

重点提示

3.2.18.0版本更新注意：

需要集成com.getui:gtc:3.2.5.0及以上版本。

3.2.17.0版本更新注意：

  • 需要集成com.getui:gtc:3.2.4.0及以上版本。

其他版本更新注意：

  • 移除 Gradle 中 GETUI_APP_KEY、GETUI_APP_SECRET、配置，GETUI_APP_ID 改为 GETUI_APPID, AndroidManifest 中仅保留 GETUI_APPID 占位符。
  • 为兼容 Android 9.0，请在 application 节点添加 android:usesCleartextTraffic="true"；
  • 简化集成步骤，只需调用新增 PushManager.getInstance().initialize(Context context) 接口即可完成 SDK 初始化， 个推 SDK 会自动去寻找相应的 PushService 和 GTIntentService，无需在代码中注册自定义的PushService以及再次调用 PushManager.getInstance().registerPushIntentService(Context context, Class<T> userIntentService) 进行 IntentService 注册，详细步骤见本教程说明。建议替换原有的PushManager.getInstance().initialize(Context context, Class<T> userServiceName)接口。
  • 原先使用 2.9.5.0 以下版本的用户，升级前请删除所有已集成配置。
  • 接口变动：
    • 移除 PushManager.getInstance().stopService() 接口。
    • 废弃原有的 PushManager.getInstance().initialize(Context context, Class<T> userServiceName) 、PushManager.getInstance().registerPushIntentService(Context context, Class<T> userIntentService)接口。
    • 新增PushManager.getInstance().initialize(Context context) 接口进行初始化，推荐使用该接口进行初始化。
    • 新增PushManager.getInstance().setDebugLogger(Context context, IUserLoggerInterface loggerInterface) 接口，用于调试日志输出。

1. 创建个推应用

请参考 创建应用 获取相应的AppID信息。该信息在之后的步骤配置中将会使用。

2. Maven 集成

注意：如果过去是手动集成方式切换到 Maven 集成，则需删除原有集成配置再进行新集成。

2.1 配置 Maven 库地址

在项目根目录 build.gradle 文件的 allprojects.repositories 块中，添加个推 maven 库地址 maven { url "https://mvn.getui.com/nexus/content/repositories/releases/"}，如下所示：

buildscript {
    repositories {
        mavenCentral()
        google()
    }
    dependencies {
        ......
    }
}

allprojects {
    repositories {
        mavenCentral()
        google()
        maven {
            url "https://mvn.getui.com/nexus/content/repositories/releases/"
        }
    }
}

2.2 配置依赖

  1. 配置 SDK 依赖及应用参数：在 app/build.gradle 文件的 dependencies 块中引用个推 SDK 依赖 implementation 'com.getui:gtsdk:${version}'，此处的 ${version} 为对应的 SDK 版本号，并在android.defaultConfig 下添加 manifestPlaceholders，配置个推相关的应用参数， 如下所示：

        ......

    android {
        defaultConfig {
            manifestPlaceholders = [
                  //从 3.1.2.0 版本开始，APPID 占位符从 GETUI_APP_ID 切换为 GETUI_APPID 
                  //后续所有产品的 APPID 均统一配置为 GETUI_APPID 占位符
                GETUI_APPID       : "your appid",
            ]        
        }
      ......
    }

    dependencies {
        implementation 'com.getui:gtsdk:3.3.8.0'  //个推SDK
        implementation 'com.getui:gtc:3.2.17.0'  //个推核心组件
    }

2.3 其他说明（重要）

对于同时集成个推多个产品 SDK 且多个 SDK APPID 值不一致的用户:

  1. 可以任选一个产品 APPID 配置到 GETUI_APPID 占位符中;
  2. 其余 SDK 在 AndroidManifest 文件中务必添加对应的标签来补充APPID, 具体如下:
<application>

  ....
  <!--个推SDK的appid 重要！必须补充-->
  <meta-data
        android:name="PUSH_APPID"
    android:value="个推SDK的appid" />

  <!-- 补充个验SDK的appid -->
  <meta-data
        android:name="GY_APP_ID"
    android:value="个验SDK的appid" />

  <!-- 补充个数SDK的appid -->
  <meta-data
        android:name="GS_APPID"
    android:value="个数SDK的appid" />

  <!-- 补充个像SDK的appid -->
  <meta-data
        android:name="GI_APPID"
    android:value="个像SDK的appid" />

  ....
</application>

AndroidManifest文件添加标签，适配 android11及以上

  • queries标签对gradle版本有要求，建议升级到4.0.1及以上。或使用3.3.3 、3.4.3 、 3.5.4 、 3.6.4版本
</manifest>

//......
 <queries>
        <intent>
            <action android:name="com.getui.sdk.action" />
        </intent>
    </queries>
//......

</manifest>

2.4 配置可选权限

上述接入方式已包含个推服务所需的所有必备权限。在此之外，您还可以配置以下可选权限，以便使用个推提供的电子围栏功能。请在AndroidManifest.xml的<manifest>根标签下添加如下配置：

<!-- iBeancon 功能所需权限 -->
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
<!-- 个推电子围栏功能所需权限 -->
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

3. 配置推送服务

为了让推送服务在部分主流机型上更稳定运行，从 2.9.5.0 版本开始，个推支持第三方应用配置使用自定义 Service 来作为推送服务运行的载体。

  1. 在项目源码中添加一个继承自 com.igexin.sdk.PushService 的自定义 Service：

    package com.getui.demo.service;
public class DemoPushService extends com.igexin.sdk.PushService {
}

  2. 在 AndroidManifest.xml 中添加上述自定义 Service，（使用 maven 集成，android:process 属性必须为 pushservice。手动集成方式也请保证与其他组件进程名一致，建议复制本文档的默认配置即可），如下：

     <!-- 请根据您当前自定义的 PushService 名称路径进行配置-->
  <service
      android:name="com.getui.demo.service.DemoPushService"
      android:exported="false"
      android:label="PushService"
      android:process=":pushservice"/>

4. 设置通知图标

客户端必须配置 push_small.png 资源文件，若客户端无该文件，会导致通知栏消息无法展示。

  1. 设置通知栏及通知栏顶部图标：为了修改默认的通知图标以及通知栏顶部提示小图标，请务必在资源目录的 res/drawable-ldpi/、res/drawable-mdpi/、res/drawable-hdpi/、res/drawable-xhdpi/、res/drawable-xxhdpi/ 等各分辨率目录下，放置相应尺寸的文件名为 push.png 和 push_small.png 的图片（该图片内容为您应用自定义的图标文件），如图所示：

    Getui_SDK_Demo_AS_official/
    |- app/
    |    |- src/
    |       |- main/
    |         |- res/
    |             |- drawable-hdpi/
    |                 |- push.png
    |                 |- push_small.png
    |             |- drawable-ldpi/
    |                 |- push.png
    |                 |- push_small.png
    |             |- drawable-mdpi
    |                 |- push.png
    |                 |- push_small.png
    |             |- drawable-xhdpi
    |                 |- push.png
    |                 |- push_small.png
    |             |- drawable-xxhdpi
    |                 |- push.png
    |                 |- push_small.png
    | ......

    push_small.png 会展示在顶部状态栏和通知左上角位置，push_small 只能内置, 不能修改。push.png 将会作为通知展示图标，请务必确认您放置的图标内容无误。建议的 push.png 图片尺寸和 push_small.png 图片尺寸分别如下：

    //push.png 图片尺寸
ldpi:    48*48
mdpi:    64*64
hdpi:    96*96
xhdpi:   128*128
xxhdpi:  192*192

//push_small.png 图片尺寸
ldpi:    18*18
mdpi:    24*24
hdpi:    36*36
xhdpi:   48*48
xxhdpi:  72*72
xxxhdpi:  96*96

    另外，国产手机可以直接使用应用图标，但是在海外版手机的push_small.png 有以下四个注意要点：1. 必须是带 Alpha 透明通道的 PNG 图片。 2.背景必须是透明的。 3.图形必须是白色。 4. 周围不宜留过多的 padding。

  2. 配置多套通知栏图标：如果您需要根据不同推送场景切换不同通知栏图标或者其他配置多套通知栏图标的场景，可以参考以下步骤：

    • 首先，在资源目录的 res/drawable-ldpi/、res/drawable-mdpi/、res/drawable-hdpi/、res/drawable-xhdpi/、res/drawable-xxhdpi/ 等各分辨率目录下放置相应的多套通知图标，例如 push1.png、push2.png，如下：

      Getui_SDK_Demo_AS_official/
    |- app/
    |    |- src/
    |       |- main/
    |         |- res/
    |             |- drawable-hdpi/
    |                 |- push1.png
    |                 |- push2.png
    |                 |- push_small.png
    |             |- drawable-ldpi/
    |                 |- push1.png
    |                 |- push2.png
    |                 |- push_small.png
    |             |- drawable-mdpi
    |                 |- push1.png
    |                 |- push2.png
    |                 |- push_small.png
    |             |- drawable-xhdpi
    |                 |- push1.png
    |                 |- push2.png
    |                 |- push_small.png
    |             |- drawable-xxhdpi
    |                 |- push1.png
    |                 |- push2.png
    |                 |- push_small.png
    | ......
    • 然后，通过服务端推送 API，Style 样式 API 中的 setLogo 方法指定通知栏图标的名称，例如 style.setLogo("push1.png") 来指定要切换展示的对应名称的通知图标（仅切换通知栏图标），详见 服务端推送模版。

5. 其他配置

5.1 资源精简配置

5.1.1 shrinkResources

如果您的工程启用了资源精简，即如果在 app/build.gradle 的 android.buildTypes.release 下配置了 shrinkResources true，为了避免个推 SDK 所需资源被错误精简导致功能异常，需要在项目资源目录 res/raw 中添加 keep.xml 文件，并在 keep.xml 文件中使用 tools:keep 定义哪些资源需要被保留（资源之间用“,”隔开），如 tools:keep="@drawable/push,@drawable/push_small,...,"，此处 @drawable/push、@drawable/push_small 通知图标的名称应为您当前放着于应用中的图标名称，如下：

<?xml version="1.0" encoding="utf-8"?>
<resources
    xmlns:tools="http://schemas.android.com/tools"
    tools:keep="......,
    @drawable/push,
    @drawable/push_small"/>
    <!-- 若您需要使用其他自定义推送图标，也需要在此处添加 -->

5.1.2 AndResGuard

如果您的工程使用了 AndResGuard 进行资源精简，为了避免个推 SDK 所需资源被错误精简导致功能异常，需要为个推添加白名单配置。gradle 集成 AndResGuard 的方式，需要您在 AndResGuard 的 whiteList 节点下添加如下代码：

andResGuard {
    ......
    whiteList = [
           ......
           // for getui
           "R.drawable.push",        
           "R.drawable.push_small"
           // 若您需要使用其他自定义推送图标，也需要在此处添加，此处的 R.drawable.push，R.drawable.push_small 应为您当前放置的推送图标。
    ]
    ......
}

命令行使用 AndResGuard 的方式，需要您在 config.xml 文件中的 节点下添加如下代码：

<issue id="whitelist" isactive="true">
    <path value="<your_package_name>.R.drawable.push"/>
    <path value="<your_package_name>.R.drawable.push_small"/>
    <!-- 若您需要使用其他自定义推送图标，也需要在此处添加，此处的 R.drawable.push，R.drawable.push_small 应为您当前放置的推送图标。 -->
</issue>

6. 编写集成代码

6.1 初始化 SDK 、注册 CID 和自定义接收服务事件

  1. 初始化 SDK

    • 调用个推初始化代码：com.igexin.sdk.PushManager.getInstance().preInit(Context context) 进行 SDK 的初始化。**我们建议开发者在 Application.onCreate() 和主 Activity.onCreate() 方法中初始化个推 SDK。多次调用 SDK 初始化并无影响。注意：此时SDK功能尚未启用，推送 CID 暂未生成
      为了保证 SDK 服务稳定，开发者需在 App《隐私政策》的 “与授权合作伙伴共享”条款中，将 个推的用户隐私政策 加入其中。并确保在 App 首次运行时通过明显方式提示终端用户阅读您的 App《隐私政策》，取得终端用户的合法授权后，再初始化 SDK ，详情可查看：个推合规指南 。
    • 另外，为了保证推送通知更好的触达用户，降低用户对于通知开关设置的难度，我们建议在应用代码中引导用户前往通知页面打开允许应用通知开关，具体实现代码可以参考 Demo 工程。

  2. 注册 CID

    • 调用个推注册 CID 代码：com.igexin.sdk.PushManager.getInstance().initialize(Context context) 进行推送 CID 的注册。
      为了保障推送功能可以正常使用，您务必确保用户同意《隐私政策》之后，调用初始化和注册 CID 方法。若不调用注册 CID 方法，推送功能无法正常使用。

  3. 自定义接收推送服务事件

    • 在项目源码中添加一个继承自 com.igexin.sdk.GTIntentService 的类，用于接收 CID、透传消息以及其他推送服务事件。请参考下列代码实现各个事件回调方法：

      package com.getui.demo;

import android.content.Context;
import android.util.Log;

import com.igexin.sdk.GTIntentService;
import com.igexin.sdk.message.GTCmdMessage;
import com.igexin.sdk.message.GTNotificationMessage;
import com.igexin.sdk.message.GTTransmitMessage;

/**
 * 继承 GTIntentService 接收来自个推的消息，所有消息在主线程中回调，如果注册了该服务，则务必要在 AndroidManifest 中声明，否则无法接受消息
 */
public class DemoIntentService extends GTIntentService {

    @Override
    public void onReceiveServicePid(Context context, int pid) {
    }

    /**
    * 此方法用于接收和处理透传消息。透传消息个推只传递数据，不做任何处理，客户端接收到透传消息后需要自己去做后续动作处理，如通知栏展示、弹框等。
    * 如果开发者在客户端将透传消息创建了通知栏展示，建议将展示和点击回执上报给个推。
    */
    @Override
    public void onReceiveMessageData(Context context, GTTransmitMessage msg) {
        byte[] payload = msg.getPayload();
        String data = new String(payload);
        Log.d(TAG, "receiver payload = " + data);//透传消息文本内容

        //taskid和messageid字段，是用于回执上报的必要参数。详情见下方文档“6.2 上报透传消息的展示和点击数据”
        String taskid = msg.getTaskId();
        String messageid = msg.getMessageId();

    }

    // 接收 cid
    @Override
    public void onReceiveClientId(Context context, String clientid) {
        Log.e(TAG, "onReceiveClientId -> " + "clientid = " + clientid);
    }

    // cid 离线上线通知
    @Override
    public void onReceiveOnlineState(Context context, boolean online) {
    }

    // 各种事件处理回执
    @Override
    public void onReceiveCommandResult(Context context, GTCmdMessage cmdMessage) {
    }

    // 通知到达，只有个推通道下发的通知会回调此方法
    @Override
    public void onNotificationMessageArrived(Context context, GTNotificationMessage msg) {
    }

    // 通知点击，只有个推通道下发的通知会回调此方法
    @Override
    public void onNotificationMessageClicked(Context context, GTNotificationMessage msg) {   
    }
}

    • 在 AndroidManifest.xml 中配置上述 IntentService 类，如下：

      <service
    android:name="com.getui.demo.service.DemoIntentService" />

6.2 上报透传消息的展示和点击数据

透传消息：个推只传递数据，不做任何处理，客户端接收到透传消息后需要自己去做后续动作处理，如通知栏展示、弹框等。

如果开发者自己本地将 “透传消息” 创建了通知栏展示，建议执行相应动作后，将 ”展示“ 和 ”点击“ 回执上报给个推。可帮助您完善推送数据、且支持更精确的运营场景。

以下是上报 展示和点击 数据的示例代码，taskid 和 messageid 字段从 onReceiveMessageData 透传回调获取：

      /**
      * 上报个推透传消息的展示回执。如果透传消息本地创建通知栏消息“展示”了，则调用此方法上报。
      */
      public boolean pushGtShow(Context context, String taskid ,String messageid) {
          int gtactionid = 60001;//gtactionid传入60001表示个推渠道消息展示了
          boolean result = PushManager.getInstance().sendFeedbackMessage(context, taskid, messageid, gtactionid);
          return result;
      }

      /**
      * 上报个推透传消息的点击回执。如果透传消息本地创建通知栏消息被“点击”了，则调用此方法上报。
      */
      public boolean pushGtClick(Context context, String taskid ,String messageid) {
          int gtactionid = 60002;//gtactionid传入60002表示个推渠道消息点击了
          boolean result = PushManager.getInstance().sendFeedbackMessage(context, taskid, messageid, gtactionid);
          return result;
      }

7. 验证推送

  1. 查看调试日志信息

    • 在 Application 的 onCreate 中添加以下代码：
      com.igexin.sdk.PushManager.getInstance().setDebugLogger(this, new IUserLoggerInterface() {
    @Override
    public void log(String s) {
        Log.i("PUSH_LOG",s);
    }
});

    • 连接手机或启动 Android 模拟器，编译运行你的工程，查看 logcat 信息。过滤 logcat 中的 PUSH_LOG 信息，如果看到 Login successed with cid = xxx 日志输出，则说明 SDK 初始化成功。

          [GT-PUSH] [PushManager]Start initializing sdk
    [GT-PUSH] [PushManager]start pushService = com.getui.demo.DemoPushServiceNew
    [GT-PUSH] [LOG-LogController] Sdk version = 3.0.1.0
    [GT-PUSH] [PushManager]call registerPushIntentService
    [GT-PUSH] onHandleIntent() = get sdk service pid 
    [GT-PUSH] ServiceManager start from initialize...
    [GT-PUSH] Start login appid = TI85ilD*******L89MFNV appkey = 1qNlp*******BP9COgYjA
    [GT-PUSH] Login successed with cid = e3f004e873f9a5d9e2e006c4a9ca2f5f
    [GT-PUSH] onHandleIntent() = received client id

    注意：com.igexin.sdk.PushManager.getInstance().setDebugLogger 接口仅限调试的时候使用，切勿发布到线上版本，重复调用仅以第一次为准。 可以任意顺序调用该接口与个推初始化接口，但建议紧邻着个推初始化接口调用该接口。 如果看到 Warning! the log cache is too long to show the full content,we suggest you call initialize and setDebugLogger in a short time interval. 这样的提示请调整调用时间间隔。

  2. 测试推送功能

    • 登录 个推 ，点击相应应用创建推送，进入待测试应用的推送通知界面：
      img_as_conlose

    • 依次填写通知标题和通知内容，点击发送按钮即可向该推送应用名下所有 CID 推送通知消息。具体推送操作方法详见：创建推送通知，下拉通知栏，如果手机或模拟器收到消息，那么恭喜您，个推 SDK 接入测试已经成功完成！

8. 常见问题

  • 如果无法获取cid，建议调用PushManager.getInstance().checkManifest()接口检查集成结果！此接口会自动检测运行环境且只在debug状态下时才会工作，线上release版本不会被执行。
  try {
      PushManager.getInstance().checkManifest(this);
  } catch (Exception e) {
      e.printStackTrace();
  }
  • 在logcat过滤GetuiPushException日志。若有集成问题会打印类似如下日志：
W/System.err:     at com.getui.demo.GetuiSdkDemoActivity.test(GetuiSdkDemoActivity.java:115)
W/System.err:     at com.getui.demo.GetuiSdkDemoActivity.onCreate(GetuiSdkDemoActivity.java:25)
  • 更多详细信息可参考个推 SDK 集成 Demo，资料包中的路径如下：
GETUI_ANDROID_SDK/
  | - Demo 工程/
  |    |- Getui_SDK_Demo_AS_maven/ （AndroidStudio 快速集成 Demo 工程）

更多问题详见 FAQ

在这篇文章中： 前言    重点提示 1. 创建个推应用 2. Maven 集成 3. 配置推送服务 4. 设置通知图标 5. 其他配置 6. 编写集成代码 7. 验证推送 8. 常见问题
开发者中心 SDK 下载

文档中心搜索

技术
咨询

微信扫一扫

随时联系技术支持

在线
咨询