运营中心SDK集成文档

运营中心SDK集成文档

运营中心SDK(IOP-SDK)提供数据统计和推送功能,本篇文档分为三个部分介绍如何集成IOP-SDK:

  1. SDK集成
  2. 数据统计接入
  3. 推送接入

SDK集成

创建应用

1.登录个推开发者中心,点击【我的】-【应用管理】-【+创建应用】

img_getui_start_devcenter_0

2.选择需开通的个推产品及应用平台,上传应用图片,填写应用名称、简介及android包名、android签名、ios bundleID等信息,点击【去集成】按钮

img_getui_start_devcenter_1

3.查看应用信息,记录appId、appKey、appSecret、masterSecret等信息

img_getui_start_devcenter_2

以上参数在后续的集成中会用到。

aar包集成方式

将资源文件中的iop-xxxx.aar以及gtc-xxxx.aar一起复制到app模块下面的libs文件夹中。

打开 app/build.gradle ,在 dependencies 中添加相应的包的依赖 :

image-20200709103038565

dependencies {
    implementation(name: 'iop-1.0.0.0', ext: 'aar')
    implementation(name: 'gtclite-1.0.0.0', ext: 'aar')
}

SO文件配置

将资源包中的so目录下的文件复制到libs目录下面:

image-20200709103356630

SDK配置

应用参数配置

app/build.gradle 文件中的 android.defaultConfig 下添加 manifestPlaceholders ,配置相关的应用参数,如下图所示:

image-20200709103744830

manifestPlaceholders = [
        GETUI_APP_ID      : "c6nxM5Rbz7A1tDkMoT5TN",
        GT_INSTALL_CHANNEL: "APP_CHANNEL",
        GETUI_APP_KEY     : "kx7ldWctdi8u9XDmGCMiH8",
        GETUI_APP_SECRET  : "omQD7JvXuwALANItQU4a36",
]

其中,GETUI_APP_IDGETUI_APP_KEYGETUI_APP_SECRET是从个推申请的应用参数,可以从开发者中心的相关应用信息里面获取。

GT_INSTALL_CHANNEL为将要发布的渠道(渠道若为纯数字字符串不能超过int表示的范围) 。

混淆配置

代码混淆配置

在混淆文件中加入如下配置即可:

-dontwarn com.getui.**
-keep class com.getui.**{*;}
-dontwarn com.igexin.**
-keep class com.igexin.**{*;}

资源混淆配置

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"/>
    <!-- 若您需要使用其他自定义推送图标,也需要在此处添加 -->
AndResGuard

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

andResGuard {
    ......
    whiteList = [
           ......
           // for getui
           "R.drawable.push",        
           "R.drawable.push_small"
           "R.layout.geshu_*"
           "R.id.geshu_*"
           // 若您需要使用其他自定义推送图标,也需要在此处添加,此处的 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"/>
    <path value="<your_package_name>.R.layout.geshu_*"/>
    <path value="<your_package_name>.R.id.geshu_*"/>
    <!-- 若您需要使用其他自定义推送图标,也需要在此处添加,此处的 R.drawable.push,R.drawable.push_small 应为您当前放置的推送图标。 -->
</issue>

数据统计接入

数据统计功能的入口通过以下方式获取:

GsManager gsManager = IopManager.getGsManager();

初始化

在您应用的启动入口(Application的onCreate中)调用SDK的初始化代码:

IopManager.getGsManager().init(this);

设置开发者模式

默认开关是关闭的,可以通过以下代码开启开发者模式:

GsConfig.setDebugEnable(true);

该模式下,数据会实时上传,且将输出 SDK 相关日志。

注意: 上线时请关闭开关或者注释该行代码。

应用时长统计

应用时长统计用于统计启动次数和应用的真实活跃时长,集成 SDK 后不需要开发者调用额外的接口。

其中 Android 平台一次完整的启动包括如下两种情况:

1.从启动应用到关闭应用

2.从启动应用到应用退至后台,且在后台运行时间超过 30s 。也可以修改该默认值:

void GsConfig.setSessionTimoutMillis(long time);

注意:GsConfig 配置类需要在 SDK 初始化之前配置。

自定义事件

自定义事件可以统计某些用户自定义埋点的发生时间以及次数,例如广告点击、短信数量等。通常 event_id用于表示某种行为或功能的统计(如统计“发送”按钮被触发多少次),而参数则用于标识统计的具体对象(如功能为“下载”的按钮),由 event_id 唯一标识一个事件。

自定义事件主要分为三种:

(1)次数统计:统计指定行为被触发的次数。

(2)时长统计:统计指定行为消耗的时间,单位为秒。需要 eventBegineventEnd 接口成对使用才可生效。

(3)用户属性统计:统计对应用户的相关信息。

每类事件都支持使用 jsonObject 参数类型。其中 key 为字符串类型,且不能与 SDK 预置属性重复(具体预置属性见文末),value 目前支持类型有 StringNumberBooleanDate

次数统计事件

在事件执行开始时调用次数统计方法,SDK 会根据事件 ID ,统计该事件被点击的次数。

void  IopManager.getGsManager().onEvent(String eventId, JSONObject jsonObject)

参数:

  • eventId :自定义事件 Id ,用于标识事件的唯一
  • jsonObject : key-value ,自定义属性,用于扩展统计需求

示例代码

public void onClick(View v) {
            // jsonObject 可不传
        try {
            JSONObject jsonObject = new JSONObject();
            jsonObject.put("buttonId", "onclick");
            IopManager.getGsManager().onEvent("eventId", jsonObject);
        } catch (JSONException e) {
            e.printStackTrace();
        }
}
时长统计事件

在事件开始和结束时调用对应方法,可以获取并上传事件的时间。

//事件开始
void IopManager.getGsManager().onBeginEvent(String eventId, JSONObject jsonObject)
//事件结束
void IopManager.getGsManager().onEndEvent(String eventId, JSONObject jsonObject)

参数:

  • eventId :自定义事件 Id ,用于标识事件的唯一
  • jsonObject : key-value ,自定义属性,用于扩展统计需求,开始和结束点的 jsonObject 必须一致计时事件才会生效

示例代码

public void onClick(View v) {
    // jsonObject 可不传
        try {
            JSONObject jsonObject = new JSONObject();
            jsonObject.put("type", "download");
            IopManager.getGsManager().onBeginEvent("eventId", jsonObject);
            IopManager.getGsManager().onEndEvent("eventId", jsonObject);
        } catch (JSONException e) {
            e.printStackTrace();
        }
}
用户属性设置

设置⽤户属性,记录的是用户的基本固定不变的属性,例如性别、年龄、注册时间、注册地域、注册渠道等。

void IopManager.getGsManager().setProfile(JSONObject jsonObject)

参数:

  • jsonObject : key-value ,自定义用户属性,用于扩展统计需求

示例代码

public void onClick(View v) {
        try {
            JSONObject jsonObject = new JSONObject();
            jsonObject.put("sex","男");
            jsonObject.put("age", 22);
            IopManager.getGsManager().setProfile(jsonObject);
        } catch (JSONException e) {
            e.printStackTrace();
        }
}

用户属性设置

用户预置属性允许开发者自己上传。

IopManager.getGsManager().setProfile(param_json);

预置属性说明

事件预置属性

事件预置属性用 $ 标记(预置属性由sdk采集,开发者不可以修改):

字段名称 类型 说明
$country 字符串 国家
$city 字符串 城市
$province 字符串 省份
$app_version 字符串 应用的版本
$channel 字符串 渠道
$time 数值 事件产生时间
$lib_version 字符串 SDK版本
$manufacturer 字符串 设备制造商,例如Apple
$model 字符串 设备型号,例如iphone6
$os 字符串 操作系统,例如iOS
$os_version 字符串 操作系统版本,例如8.1.1
$screen_height 数值 屏幕高度,例如1920
$screen_width 数值 屏幕宽度,例如1080
$wifi 布尔值 是否使用wifi,例如true
$carrier 字符串 运营商名称,例如ChinaNet
$network_type 字符串 网络类型,例如4G
$duration 数值 计时事件时长
用户预置属性

$first_visit_timesdk 采集。

字段名称 类型 说明
$country 字符串 国家
$city 字符串 城市
$province 字符串 省份
$name 字符串 姓名
$sex 字符串 性别
$phone 字符串 手机号
$email 字符串 邮箱
$birthday 日期 出生日期
$signup_time 日期 注册时间
$first_visit_time 日期 首次访问时间

推送接入

推送功能的入口通过以下方式获取:

PushManager pushManager = IopManager.getPushManager();

配置推送服务

为了让推送服务在部分主流机型上更稳定运行,个推支持第三方应用配置使用自定义 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="true"
         android:label="PushService"
         android:process=":pushservice"/>
    

设置通知图标

  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
    xxxhdp:  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.pngpush2.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") 来指定要切换展示的对应名称的通知图标(仅切换通知栏图标),详见 服务端推送模版

    编写集成代码

    1. 初始化 SDK

      • 调用个推初始化代码:IopManager.getPushManager().initialize(Context context) 进行 SDK 的初始化。我们建议开发者在 Application.onCreate() 和主 Activity.onCreate() 方法中初始化个推 SDK。多次调用 SDK 初始化并无影响。为了保证 SDK 服务稳定,推荐引导用户授权相关的隐私权限
      • 另外,为了保证推送通知更好的触达用户,降低用户对于通知开关设置的难度,我们建议在应用代码中引导用户前往通知页面打开允许应用通知开关。
    2. 自定义接收推送服务事件

      • 在项目源码中添加一个继承自 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) {
              // 透传消息的处理
          }
      
          // 接收 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"
          android:permission="android.permission.BIND_JOB_SERVICE"/>
      

    验证推送

    1. 查看调试日志信息

      • 在 Application 的 onCreate 中添加以下代码:
      IopManager.getPushManager().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] load so = getuiext3 by system success
          [GT-PUSH] Start login appid = TI85ilD*******L89MFNV appkey = 1qNlp*******BP9COgYjA
          [GT-PUSH] Login successed with cid = e3f004e873f9a5d9e2e006c4a9ca2f5f
          [GT-PUSH] onHandleIntent() = received client id 
      

      注意:IopManager.getPushManager().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 接入测试已经成功完成!

    常见问题

    更多问题详见 FAQ

在这篇文章中: SDK集成 数据统计接入 推送接入

文档中心搜索