无埋点 SDK 集成

无埋点 SDK 具备自动采集基本的用户行为事件,比如访问,页面浏览,元素点击等行为数据。同时也包含埋点SDK的所有功能。

准备条件

获取项目ID,请参考查看项目基本信息

获取 URL Scheme,在 GrowingIO 平台创建对应的应用时会生成 URL Scheme。请参考创建应用

1. 添加依赖

Gradle 编译环境:Android Studio

App 适配最低系统版本:Android 4.2 及以上

1. 添加工程依赖

在 project 级别的 build.gradle 文件中添加vds-gradle-plugin依赖。

示例代码:

buildscript {
    repositories {
        jcenter()
        // sdk2.9.0版本开始迁移到了Maven Central
        mavenCentral()
        google()
    }
    dependencies {
        //gradle 建议版本
        classpath 'com.android.tools.build:gradle:3.2.1'
        //GrowingIO 无埋点 SDK
        classpath 'com.growingio.android:vds-gradle-plugin:autotrack-2.10.0'
    }
}

在 module 级别的 build.gradle 文件中添加com.growingio.android插件、vds-android-agent依赖和对应的资源。

代码示例:

apply plugin: 'com.android.application'
//添加 GrowingIO 插件
apply plugin: 'com.growingio.android'
android {
    defaultConfig {
        resValue("string", "growingio_project_id", "您的项目ID")
        resValue("string", "growingio_url_scheme", "您的URL Scheme")
    }
}
dependencies {
    //GrowingIO 无埋点 SDK
    implementation 'com.growingio.android:vds-android-agent:autotrack-2.10.0'
}

2. 添加 URL Scheme 和应用权限

URL Scheme 是您在 GrowingIO 平台创建应用时生成的该应用的唯一标识。把 URL Scheme 添加到您的项目中,以便在使用圈选,Mobile Debugger,及深度链接功能时唤醒您的应用。

将 URLScheme 和应用权限添加到您的 AndroidManifest.xml 中的 LAUNCHER Activity 下。

代码示例:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.growingio.testdemo">

    <!-- GIO 需要的权限 -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
    <!-- GIO 需要的权限 -->

    <!--请注意<application/>标签中的name属性值(这里为android:name=".MyApplication")必须为您的Application类-->
    <application
        android:name=".MyApplication"
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
            <!--请添加这里的整个 intent-filter 区块,并确保其中只有一个 data 字段-->
            <intent-filter>
                <data android:scheme="growing.您的URL Scheme" />
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
            </intent-filter>
            <!--请添加这里的整个 intent-filter 区块,并确保其中只有一个 data 字段-->
        </activity>
    </application>
</manifest>

请添加一整个 intent-filter 区块,并确保其中只有一个 data 字段。

建议不要尝试修改或者合并 GIO 的 intent filter ,Google Andorid 官方解释

3. SDK初始化配置

请将 GrowingIO.startWithConfiguration 加在您的 Application 的 onCreate 方法中。为使 App 合规,请参考合规步骤

示例代码:

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        GrowingIO.startWithConfiguration(this, new Configuration()
            .trackAllFragments()
            // 建议使用 BuildConfig 设置
            .setChannel("XXX应用商店")
            
        );
    }
}

注意事项

trackAllFragments方法如果在初始化时调用,APP 内部的 Fragment 将代替 Activity 作为页面,一个 Activity 中包含多个 Fragment 时大概率会使用面积最大的 Fragment 作为当前页面的页面浏览事件( page )。

4. 代码混淆

如果您启用了混淆,请在 proguard-rules.pro 中添加如下代码:

SDK 2.6.0 更新了混淆文件,前后混淆文件内容截然不同,请注意更新。

-keep class com.growingio.** {
    *;
}
-dontwarn com.growingio.**
-keepnames class * extends android.view.View
-keepnames class * extends android.app.Fragment
-keepnames class * extends android.support.v4.app.Fragment
-keepnames class * extends androidx.fragment.app.Fragment
-keep class android.support.v4.view.ViewPager{
    *;
}
-keep class android.support.v4.view.ViewPager$**{
      *;
}
-keep class androidx.viewpager.widget.ViewPager{
    *;
}
-keep class androidx.viewpager.widget.ViewPager$**{
      *;
}

如果您使用了 AndRestGuard,请在白名单里添加 GrowingIO。

代码示例:

R.string.growingio*

5. lambda 表达式支持配置

lambda 表达式目前业界主流两种,分别为 retrolambda 和 AndroidStudio 支持的 lambda。

GrowingIO 的SDK 只支持 AndroidStudio 自带的 lambda 表达式。

  • SDK版本<2.7.4时,对于 android.enableD8.desugaring = true 未做兼容。 在com.android.tools.build:gradle:3.2.1 之后, Google默认开启 desugaring 特性, 暂时需要用户手动关闭。

//关闭方法:在项目根目录中 gradle.properties 文件中增加以下配置:
android.enableD8.desugaring=false
  • SDK版本>=2.7.4时,兼容了android.enableD8.desugaring = true,无需再做配置。

6. 设置SDK异常上传开关

SDK默认会开启收集SDK内部异常上报至服务端功能,方便开发更好的追踪SDK问题和完善SDK功能。如果您不希望收集SDK内部异常,或者和您的 crash 收集框架有冲突,您可以关闭该功能。

setUploadExceptionEnable(boolean uploadExceptionEnable)

参数说明:

参数名

类型

必填

默认值

说明

uploadExceptionEnable

boolean

true

开关SDK异常上传功能,true开启,false关闭

代码示例:

GrowingIO.startWithConfiguration(this, new GTouchConfig()
    .setUploadExceptionEnable(true)
    ...
);

2. 重要配置

1. 自定义控件点击事件

如果您有自定义控件重写了ViewonTouchEvent方法来判断和处理点击事件,那么必须调用它的performClick,并且设置相应的onClickListener

代码示例:

// 自定义控件示例
class CustomView extends View {
    ...
    @Override
    public boolean onTouchEvent(MotionEvent event) {
      ...
      performClick();
      ...
    }
    ...
}
// 应用示例
CustomView view = findViewById(R.id.view);
view.setOnClickListener(new View.OnClickListener() { ... })

或者使用手动调用系统点击事件方法。 请参考点击事件采集逻辑。

2. 设置页面名称

对于安卓应用,页面指的是ActivityFragment

有些时候,当您代码中的原有页面不足以支持业务人员对页面进行识别时,您可以使用此接口设置一个容易识别的页面名称来替换页面浏览事件的p字段。参考:页面定义

为处理这种场景,我们提供了设置页面名称的方法,方法如下:

// 如果您设置的对象是Fragment,将Activity替换为Fragment即可
GrowingIO.setPageName(Activity activity, String name)

我们用Activity来举例,具体说明它的用法。

  1. 某个应用的商品列表页是用FeedActivity类实现的,所以默认的页面名称(p字段的值)是FeedActivity

  2. 现在我们想区分衣物类商品列表和食品类商品列表,分别看它们的浏览量,可以在onCreate方法中添加如下代码:

public class FeedActivity extends Activity {     
    @Override     
    protected void onCreate(Bundle savedInstanceState) {         
        super.onCreate(savedInstanceState);         
        GrowingIO.getInstance().setPageName(this, "Clothing");
     }
 }

3. 设置界面元素内容

SDK 默认不会采集 ImageView 的内容,如果您需要区分不同的ImageView,可以使用 contentDescription 来标记,也可以调用下方的方法来设置,数据表现上对应元素触发的点击事件中元素 v 字段的值 :

GrowingIO.setViewContent(View view, String contentDescription);

4. 设置界面元素ID

SDK 会使用 Layout 文件中的 ID 来识别一个元素。

如果部分元素在 Layout 文件中没有 ID,建议在 Layout 文件中添加。

对于动态生成的元素,可以使用如下方法对它设置唯一的 ID,数据表现上对应元素触发的点击事件中元素 x 字段的值 :

GrowingIO.setViewID(View view, String id);

5. 设置忽略元素

如果您需要不采集某些元素,比如倒计时元素涉及隐私的内容,可以使用此接口。

另外如果想禁止 WebView 内H5页面的数据采集,也可调用此接口。如果H5页面集成有Web JS SDK, 则此接口无法禁止Web JS SDK 采集数据。

GrowingIO.ignoreView(View view)

6. 设置元素对象

如果元素自身的内容并不能代表具体的意义,可以使用元素对象来标识,数据表现上对应元素触发的点击事件中元素 obj 字段的值 。

例如:在商品ListView添加购物车的场景中,每个商品item都含有一个加入购物车按钮,这时无法区分商品item与将它加入购物车按钮的一对一关系,此时调用此方法增加描述。

GrowingIO.setViewInfo(view view, String info);

7. 元素浏览事件的半自动采集配置

SDK版本支持:>=2.8.4

8. 设置Debug模式

Debug 模式:在 Android Studio 中通过 Logcat 查看 GrowingIO SDK 打印的数据采集发送日志。

在SDK初始化代码中添加如下配置:

setDebugMode(boolean debugMode)

参数说明

参数

类型

是否必填

说明

debugMode

boolean

开启GrowingIO日志,true开始,默认false

示例代码

GrowingIO.startWithConfiguration(this,new Configuration()
    //BuildConfig.DEBUG 这样配置就不会上线忘记关闭
    .setDebugMode(BuildConfig.DEBUG));

9. 设置Test模式

Test模式:实时发送数据,开启则不遵循移动网络状态下数据发送大小限制以及采集数据默认缓存 15 秒发送策略。为了方便开发者查看日志,一般和setDebugMode一起使用。

在SDK初始化代码中添加如下配置:

setTestMode(boolean testMode)

参数说明

参数
类型
是否必填
说明

testMode

boolean

开启测试模式,true开启,默认false

示例代码

GrowingIO.startWithConfiguration(this,new Configuration()
    //BuildConfig.DEBUG 这样配置就不会上线忘记关闭
    .setTestMode(BuildConfig.DEBUG));

10. 设置采集广告Banner数据

应用中界面上横向滚动Banner广告,如果是用通过 ViewPagerAdapterView 或者RecyclerView 实现的,请您在 Banner 创建时(包括动态创建)调用此接口来采集数据。

trackBanner(View banner,List<String> bannerDescriptions)

参数说明

参数
类型
是否必填
说明

banner

view

ViewPager、AdapterView、RecyclerView 实现的 View

bannerDescriptions

List<string>

广告内容描述,顺序需要跟 banner view 顺序一致

示例代码

 //Banner 初始化代码
 ViewPager bannerViewPager = (ViewPager)findViewById(R.id.banner);
 ...
 //GrowingIO 采集 Banner 数据
 GrowingIO.trackBanner(bannerViewPager, Arrays.asList("banner 1", "banner 2", "banner 3"));

检验数据发送日志示例

{
    "s":"02015456-079b-49cc-8b42-a5cc6136f0ec",
    // t 为事件类型 type
    "t":"clck", 
    "tm":1531990474178,
    "d":"com.growingio.android.test",
    "p":"ConvenientBannerActivity",
    "ptm":1531990413207,
    "e":[
        {
            "x":"/MainWindow/LinearLayout[0]/FrameLayout[1]/FitWindowsLinearLayout[0]#action_bar_root/ContentFrameLayout[1]/FrameLayout[0]/RelativeLayout[0]/ConvenientBanner[0]#convenientBanner/LinearLayout[0]/RelativeLayout[0]/CBLoopViewPager[0]#cbLoopViewPager/ImageView[-]",
            "tm":1531990474179,
            "idx":1,
            //假如现在滚动到第二个banner,V显示为您设置的描述
            "v":"banner 2" 
        }
    ]
}

11. 设置采集GPS数据

GrowingIO SDK 默认不采集地理位置信息。

如果您需要精确采集GPS数据,请在获取坐标后,调用接口设置位置信息。

经纬度设置为(0,0),视为无效设置。有效设置经纬度,会发送一个 vst 事件,用于携带经纬度数据上报。

如果您不调用此接口也可以,我们会根据用户的ip模糊匹配用户所在城市地区,能够在最终的数据分析时看到APP用户地域分布。

setGeoLocation(double latitude,double longitude)

参数说明

参数
类型
是否必传
说明

latitude

double

纬度

longitude

double

经度

示例代码

//北京的经纬度
GrowingIO.getInstance().setGeoLocation(39.9046900000,116.4071700000);

12. 设置采集输入框数据

GrowingIO SDK 默认仅采集输入框内容改变次数,不采集输入框内的文字。

如果您需要采集应用内某个输入框内的文字(例如搜索框)时,请使用如下接口。

调用接口后,当这个输入框失去焦点(包括应用退到后台),且输入框内容跟获取焦点前相比发生变化时,输入框内文字数据会被上报。

GrowingIO.getInstance().trackEditText(EditText editText);

参数说明

参数
类型
是否必填
说明

editText

EditText

采集输入框

示例代码

EditText editText = (EditText) findViewById(R.id.edit_text);
GrowingIO.getInstance().trackEditText(editText);
  • 对于密码输入框,即是被标记为需要采集输入框的文字,SDK不会进行采集。

  • 输入框失去焦点的时候或者 onPause 时才会触发chng事件,如果输入完成,输入框光标仍然在闪动,则不触发chng事件。为了保证数据准确性,请每次用户输入完成时,让输入框失去焦点,可使用editText.setFocusable(false);

13. 采集WebView页面数据

无埋点 SDK 会自动采集H5页面的数据,不需要特殊配置。

14. 设置内嵌H5页面锚点跳转触发页面浏览事件

GrowingIO SDK 默认情况下,不会把HashTag识别成页面 URL 的一部分,内嵌H5页面点击锚点页面跳转不计为页面浏览事件。

对于使用HashTag进行页面跳转的单页面网站应用来说,可以启用它来标识页面,HashTag的值也会记录在页面URL中。启用之后,如果用户点击页面中的锚点进行页面跳转,则发送一次页面浏览事件。

在SDK初始化代码中添加如下代码:

setHashTagEnable(boolean hashTagEnable)

如果内嵌H5页面集成了Web JS SDK,则 Web JS SDK 中 HashTag 配置有效,该接口调用无效

示例代码:

GrowingIO.startWithConfiguration(this, new Configuration().setHashTagEnable(true));

场景示例

点击 APP WebView 中“代码混淆”的锚点链接,URL 中#号后面为锚点,设置后 SDK 会发送页面浏览事件,它的链接为:​https://docs.growingio.com/docs/sdk-integration/android-sdk#4-dai-ma-hun-xiao

SDK发送对应采集数据:

{
    "u":"2e94075c-ead2-33ac-ab7f-f9611162efc4",
    "s":"78383569-3038-4bd4-b27c-349939367922",
    "tl":"Android SDK - 帮助文档",
    //t 为事件类型,page 为页面浏览事件
    "t":"page",
    "tm":1532408777047,
    "pt":"https",
    "d":"com.growingio.android.test::docs.growingio.com",
    //p 为浏览的页面
    "p":"StandardWebView::/docs/sdk-integration/android-sdk#4-dai-ma-hun-xiao",
    "rp":"https://docs.growingio.com/docs/sdk-integration/android-sdk#ji-cheng",
    "cs1":"GrowingIO",
    "appId":"fakeAppID",
    "v":"Android SDK - 帮助文档",
    "r":"WIFI",
    "gesid":434,
    "esid":153
}

15. 多进程支持

GrowingIO SDK默认不支持多进程使用, 但是可以通过confiuration进行设置支持多进程。

在SDK初始化代码中添加如下代码:

//支持多进程数据采集
setMutiprocess(boolean setMutiprocess);
//支持多进程圈选
supportMultiProcessCircle(boolean smpc);

参数说明:

参数
类型
是否必填
说明

isMultiprocess

boolean

开启多进程数据采集。默认值false

smpc

boolean

开启多进程圈选。默认值false

示例代码:

GrowingIO.startWithConfiguration(this, new Configuration()
                  .supportMultiProcessCircle(true)
                  .setMutiprocess(true)
                  );

16. GDPR数据采集开关

SDK版本支持:2.3.2及以上。

接口
含义

disableDataCollect()

遵守欧洲联盟出台的通用数据保护条例,用户不授权,不采集用户数据

enableDataCollect()

遵守欧洲联盟出台的通用数据保护条例,用户授权,采集用户数据

示例代码:

    // 初始化配置
    Configuration configuration = new Configuration();
    // 其它初始化配置如是否开启ebug等
    ...
    // 根据数据采集开关判断
    if (<未同意隐私协议>) {
        configuration.disableDataCollect();
    }
    // 初始化SDK
    GrowingIO.startWithConfiguration(application, configuration);
// 同意数据采集后,开启数据发送
GrowingIO.getInstance().enableDataCollect();

​GrowingIO SDK 提供有 Deep Link 回调接口,调用后获取回调参数,您需要根据回调参数和业务场景,添加对应的交互代码。

此 Callback 只有在应用收到来自 GIO Intent 的时候才会触发,您需要先在广告监测新建监测链接,并使用监测链接唤醒 APP 时触发此 allback 。

点击了解新建监测链接。

在 GrowingIO SDK 代码初始化部分配置。

//sdk >= 2.3.2 && sdk < 2.8.19
GrowingIO.startWithConfiguration(this, new Configuration()
                .setDeeplinkCallback(new DeeplinkCallback() {
                            @Override
                            public void onReceive(Map<String, String> params, int status) { 
                            // 这里接收您的参数,匹配键值对,跳转指定 APP 内页面
                            }
                        })
            );
//sdk >= 2.8.4, 新增参数 long appAwakePassedTime 
GrowingIO.startWithConfiguration(this, new Configuration()
                .setDeeplinkCallback(new DeeplinkCallback() {
                            @Override
                            public void onReceive(Map<String, String> params, int status, long appAwakePassedTime) { 
                            // 这里接收您的参数,匹配键值对,跳转指定 APP 内页面
                            // appAwakePassedTime 这个新的参数用来判定 APP 是否已经打开了很久才收到自定义参数,进而判断是否再继续跳转指定页面
                            }
                        })
            );

返回值说明

返回值名称
类型
说明

params

Map<String, String>

自定义参数,您自定义的键值对

status

int

DeeplinkCallback.SUCCESS :自定义参数获取成功; DeeplinkCallback.PARSE_ERROR :解析异常;DeeplinkCallback.ILLEGAL_URI :非法URI; DeeplinkCallback.NO_QUERY : 自定义参数为空。DeeplinkCallback.APPLINK_GET_PARAMS_FAILED : (SDK 2.8.4新增)AppLink 由于网络原因获取自定义参数失败

appAwakePassedTime

long

(SDK 2.8.4新增)App 唤醒到收到 GIO callback 的时间,单位毫秒。用以判断网络状态不好的情况,应用已经打开很久,才收到回调,开发人员决定是否收到参数后仍然跳转自定义的指定页面。

当返回值为 0 的时候,为 DeepLink 方式打开

//sdk >= 2.3.2 && sdk < 2.8.19
GrowingIO.startWithConfiguration(this, new Configuration()
    .setDeeplinkCallback(new DeeplinkCallback() {
                @Override
                public void onReceive(Map<String, String> params, int status) {
                     if (status == DeeplinkCallback.SUCCESS) {
                        //获得您的自定义参数,处理您的相关逻辑
                        Log.d("TestApplication", "DeepLink 参数获取成功,params" + params.toString());
                    }
                }
            })
);
//sdk >= 2.8.4, 新增参数 long appAwakePassedTime 
GrowingIO.startWithConfiguration(this, new Configuration()
    .setDeeplinkCallback(new DeeplinkCallback() {
                @Override
                public void onReceive(Map<String, String> params, int status, long appAwakePassedTime) {
                     //成功得到自定义参数,并且从 APP 打开到收到回调时间小于 1.5 秒
                     if (status == DeeplinkCallback.SUCCESS && appAwakePassedTime < 1500) {
                        //获得您的自定义参数,处理您的相关逻辑
                        Log.d("TestApplication", "DeepLink 参数获取成功,params" + params.toString());
                    }
                }
            })
);

18. 采集推送配置

Android SDK 2.6.3 及以上版本,支持采集通知的标题和内容,此功能默认关闭,如需开启,请在SDK初始化代码中设置开启采集通知,例如:

...
@Override
public void onCreate() {
       GrowingIO.startWithConfiguration(this, new Configuration()
                //如果多进程应用,需要开启GrowingIO多进程
                .setMutiprocess(true)
                .supportMultiProcessCircle(true)
                // 开启采集通知
                .enablePushTrack()
        );
        ...
}

注意:

支持推送平台
注意事项

Notification

全部支持

极光推送

1.初始化时,极光进程也需要初始化

2.如果多进程应用,需要开启GrowingIO多进程

华为推送

1.初始化时,推送进程也需要初始化

2.NC(Notification Center)消息,需要用户设置自定义字段: notification_title表示title, 与notification_content表示内容,请见表格下方图片

小米推送

1.初始化时,推送进程也需要初始化

2.SDK hook了PushMessageReceiver的onNotificationMessageArrived与onNotificationMessageClicked函数, 会触发SDK发送两条消息. 其中onNotificationMessageArrived需要系统支持

查看通知采集数据:

GrowingIO SDK 支持通知的展现和点击事件的采集,并未增加新的事件类型,而是使用了埋点事件发送,所以需要您创建埋点事件和事件级变量,事件级变量标识符为**notification_titlenotification_content,埋点事件的标识符为notification_shownotification_click** 创建事件分析,1-2小时之后即可看到数据。

19. 采集OAID

在 Android 10 版本中,非系统应用无法获取 IMEI。加上以前 Android 版本已经对 MAC 地址, AndroidID 的获取做了限制, 在 Android10 中缺少一种唯一标记设备的标识符。 在海外, Google 推荐使用 Google 的广告 ID 作为广告的唯一识别符,在国内移动安全联盟MSA 联合各大手机制造商推出了 OAID 的概念, 作为唯一广告标识符。

目前腾讯, 头条, 网易广告SDK已经要求使用 OAID, OAID 的准确性和覆盖率均满足广告场景的使用需求,Android SDK 提供采集 OAID 的能力。

注意:

OAID 为可选字段,在客户集成 MSA SDK 情况下根据配置可选采集。GrowingIO SDK 不会初始化 MSA SDK,我们仅调用其接口获取 OAID 值, 需要客户自行初始化 MSA的 SDK。

点击查看 MSA 集成步骤

与 IMEI、AndroidId、Google AD ID 配置相同, GrowingIO SDK 对OAID 提供了编译期,初始化前, 初始化后三种配置 OAID 是否采集的选项,点击查看 API 文档

3. 自定义数据上传

除上述的用户行为数据(无埋点数据)之外,GrowingIO 还提供了多种 API 接口,供您上传一些自定义的数据指标及维度 ,请参考Android SDK API > 自定义数上传API

90% 以上的用户都会上传登录用户 ID ,以便分析登录用户的数据情况。

4. 创建应用

添加代码之后,请先Clean项目,然后再进行编译,并在您的 Android App 安装了 SDK 后重新启动几次 App,保证行为采集数据自动发送给 GrowingIO,以便顺利完成检测。

在 GrowingIO 平台应用创建页面继续完成应用创建的数据检测,检测成功后应用创建成功。

5. 验证SDK是否正常采集数据

GrowingIO 为您提供多种验证SDK是否正常采集数据的方式:

方式一:Mobile Debugger

方式二:在SDK中设置了Debug模式后,在IDE编译器控制台查看数据采集日志。

方式三:(推荐数据校验

最后更新于

这有帮助吗?