弹窗 SDK (Android)
最低兼容Android版本4.2 API 17
弹窗 SDK 会根据运营人员对用户的分组情况,下发弹窗消息
电商demo集成运营参考代码:https://github.com/growingio/AndroidDemo

一、集成SDK

1. 集成GrowingIO Android埋点SDK

添加弹窗SDK前请确保您已经集成了我们公司的埋点 SDK,版本需要在 2.6.9 及以上,详细情况请移步Android埋点SDK帮助文档。最低兼容的 Android 版本为 4.2 。

2. 添加依赖

1.5.0版本后仓库从JCenter迁移到了Maven Central, 请使用mavenCentral()替换jcenter()

2.1 在app build.gradle添加SDK依赖

1
dependencies {
2
...
3
//由于弹窗底层网络库依赖OkHttp3网络库,请添加OkHttp3依赖
4
implementation "com.squareup.okhttp3:okhttp:3.12.1"
5
//弹窗SDK依赖
6
implementation "com.growingio.android:gtouch:$gtouch_version"
7
}
Copied!
$gtouch_version 为弹窗SDK版本号,现最新的版本号为请参考SDK更新日志

3. 需要的权限列表

所需权限同埋点SDK
1
<uses-permission android:name="android.permission.INTERNET" />
2
<!--非危险权限,不需要运行时请求,Manifest文件中添加即可-->
3
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
4
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/>
5
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
Copied!

4. 初始化SDK

请将以下GrowingTouch.startWithConfig加在您的Application 的 onCreate 方法中,且保证在埋点SDK初始化代码GrowingIO.startWithConfiguration
1
public class MyApplication extends Application {
2
3
@Override
4
public void onCreate() {
5
super.onCreate();
6
GrowingIO.startWithConfiguration(this, new Configuration()
7
.trackAllFragments()
8
.setDebugMode(BuildConfig.DEBUG)
9
.setChannel("XXX应用商店")
10
);
11
12
GrowingTouch.startWithConfig(this, new GTouchConfig()
13
.setEventPopupShowTimeout(5000)
14
.setEventPopupEnable(true)
15
.setPushEnable(true)
16
.setDebugEnable(BuildConfig.DEBUG)
17
.setEventPopupListener(new EventPopupListener() {
18
@Override
19
public void onLoadSuccess(String eventId, String eventType) {
20
Log.d(TAG, "onLoadSuccess: eventId = " + eventId + ", eventType = " + eventType);
21
}
22
23
@Override
24
public void onLoadFailed(String eventId, String eventType, int errorCode, String description) {
25
Log.d(TAG, "onLoadFailed: eventId = " + eventId + ", eventType = " + eventType);
26
27
}
28
29
@Override
30
public boolean onClicked(String eventId, String eventType, String openUrl) {
31
Log.d(TAG, "onClicked: eventId = " + eventId + ", eventType = " + eventType);
32
return false;
33
}
34
35
@Override
36
public void onCancel(String eventId, String eventType) {
37
Log.d(TAG, "onCancel: eventId = " + eventId + ", eventType = " + eventType);
38
39
}
40
41
@Override
42
public void onTimeout(String eventId, String eventType) {
43
Log.d(TAG, "onTimeout: eventId = " + eventId + ", eventType = " + eventType);
44
}
45
46
@Override
47
public boolean popupEventDecideShow(PopupWindowEvent popup, EventPopupDecisionAction decisionAction) {
48
String target = popup.getRule().getTarget();
49
Log.d(TAG, "popupEventDecideShow message name = " + popup.getName() + "target = " + target);
50
51
return false;
52
}
53
})
54
);
55
}
56
}
Copied!

6. 代码混淆

如果您启用了代码混淆,请务必在您的proguard-rules.pro文件里加入下面的代码:
1
#GrowingIO
2
-keep class com.growingio.** {
3
*;
4
}
5
-dontwarn com.growingio.**
6
-keepnames class * extends android.view.View
7
-keepnames class * extends android.app.Fragment
8
-keepnames class * extends android.support.v4.app.Fragment
9
-keepnames class * extends androidx.fragment.app.Fragment
10
-keep class android.support.v4.view.ViewPager{
11
*;
12
}
13
-keep class android.support.v4.view.ViewPager$**{
14
*;
15
}
16
-keep class androidx.viewpager.widget.ViewPager{
17
*;
18
}
19
-keep class androidx.viewpager.widget.ViewPager$**{
20
*;
21
}
22
23
#okhttp
24
-dontwarn okhttp3.**
25
-keep class okhttp3.**{*;}
26
27
#okio
28
-dontwarn okio.**
29
-keep class okio.**{*;}
Copied!

二、重要配置

1 设置弹窗开关

1.1 setEventPopupEnable

设置弹窗的开关,可以在初始化的时候选择关闭弹窗功能,这样弹窗SDK就不会在APP的logo页和闪屏页显示弹窗,然后在APP的内容页打开时再打开弹窗开关。
1
setEventPopupEnable(boolean eventPopupEnable)
Copied!

1.2 参数说明

参数名
类型
必填
默认值
说明
enable
boolean
true
开关弹窗功能,true开启,false关闭

1.3 代码示例

1
GrowingTouch.startWithConfig(this, new GTouchConfig()
2
.setEventPopupEnable(true)
3
...
4
);
Copied!

2 设置Debug模式(只在调试时使用,上线请务必关闭)

2.1 setDebugEnable

查看数据采集发送日志,能够在Android Studio中通过Logcat查看GrowingTouch打印的数据发送日志,在 APP 的 Application onCreate 初始化SDK地方添加配置。
1
setDebugEnable(boolean debugEnable)
Copied!

2.2 参数说明

参数名
类型
必填
默认值
说明
debugEnable
boolean
false
开启弹窗日志,true开启,false关闭

2.3 代码示例

1
GrowingTouch.startWithConfig(this, new GTouchConfig()
2
//BuildConfig.DEBUG 这样配置就不会上线忘记关闭
3
.setDebugEnable(BuildConfig.DEBUG)
4
...
5
);
Copied!

3 设置弹窗显示超时时间

3.1 setEventPopupShowTimeout

埋点事件的产生到弹窗完全显示的超时时间,如网络情况可能会影响到弹窗的加载时间,或者两个弹窗埋点事件先后触发,前面一个弹窗的显示时间过长导致后面的弹窗事件超时等等。
1
setEventPopupShowTimeout(long eventPopupShowTimeout)
Copied!

3.2 参数说明

参数名
类型
必填
默认值
说明
eventPopupShowTimeout
long
5000
埋点事件的产生到弹窗完全显示的超时时间,单位ms。0<=有效值<=100000

3.3 代码示例

1
GrowingTouch.startWithConfig(this, new GTouchConfig()
2
.setEventPopupShowTimeout(8000)
3
...
4
);
Copied!

4 弹窗的事件监听

4.1 setEventPopupListener

通过监听获取事件和参数,您可以根据事件和参数以及您的业务场景执行相关的交互。
1
setEventPopupListener(EventPopupListener eventPopupListener)
Copied!

4.2 参数说明

1
public interface EventPopupListener {
2
/**
3
* 弹窗显示成功
4
*
5
* @param eventId 埋点事件名称
6
* @param eventType 事件类型,system(弹窗SDK内置的事件)或custom(用户自定义的埋点事件)
7
*/
8
void onLoadSuccess(String eventId, String eventType);
9
10
/**
11
* 弹窗加载失败
12
*
13
* @param eventId 埋点事件名称
14
* @param eventType 事件类型,system(弹窗SDK内置的事件)或custom(用户自定义的埋点事件)
15
* @param errorCode 错误码
16
* @param description 错误描述
17
*/
18
void onLoadFailed(String eventId, String eventType, int errorCode, String description);
19
20
/**
21
* 用户点击了弹窗的有效内容。弹窗SDK现在只提供跳转APP内部界面和H5界面两种处理方式。
22
* 您可以在这里接管跳转事件,处理需要跳转的url。您也可以自定义Url协议,实现更多业务和交互功能。
23
*
24
* @param eventId 埋点事件名称
25
* @param eventType 事件类型,system(弹窗SDK内置的事件)或custom(用户自定义的埋点事件)
26
* @param openUrl 跳转的url
27
* @return true:点击事件被消费,弹窗SDK不在处理;false:由弹窗SDK处理点击事件
28
*/
29
boolean onClicked(String eventId, String eventType, String openUrl);
30
31
/**
32
* 用户关闭了弹窗
33
*
34
* @param eventId 埋点事件名称
35
* @param eventType 事件类型,system(弹窗SDK内置的事件)或custom(用户自定义的埋点事件)
36
*/
37
void onCancel(String eventId, String eventType);
38
39
/**
40
* 弹窗显示超时
41
*
42
* @param eventId 埋点事件名称
43
* @param eventType 事件类型,system(弹窗SDK内置的事件)或custom(用户自定义的埋点事件)
44
*/
45
void onTimeout(String eventId, String eventType);
46
47
/**
48
* 触达弹窗消费时(待展示时)
49
* @param popup 待展示的弹窗数据
50
*
51
* @param action 弹窗绑定的操作行为
52
*
53
* @return true:自定义展示该弹窗,触达SDK不在处理;false:由触达来展示该弹窗,
54
* @discussion 在 popup.rule.target 数据中可以取出配置的 target 数据,比如一张图片的链接或其他参数,进行自定义的弹窗展示
55
*/
56
boolean popupEventDecideShow(PopupWindowEvent popup, EventPopupDecisionAction decisionAction);
57
}
58
Copied!

4.3 代码示例

1
GrowingTouch.startWithConfig(this, new GTouchConfig()
2
.setEventPopupListener(new EventPopupListener() {
3
@Override
4
public void onLoadSuccess(String eventId, String eventType) {
5
Log.d(TAG, "onLoadSuccess: eventId = " + eventId + ", eventType = " + eventType);
6
}
7
8
@Override
9
public void onLoadFailed(String eventId, String eventType, int errorCode, String description) {
10
Log.d(TAG, "onLoadFailed: eventId = " + eventId + ", eventType = " + eventType);
11
12
}
13
14
@Override
15
public boolean onClicked(String eventId, String eventType, String openUrl) {
16
Log.d(TAG, "onClicked: eventId = " + eventId + ", eventType = " + eventType);
17
return false;
18
}
19
20
@Override
21
public void onCancel(String eventId, String eventType) {
22
Log.d(TAG, "onCancel: eventId = " + eventId + ", eventType = " + eventType);
23
24
}
25
26
@Override
27
public void onTimeout(String eventId, String eventType) {
28
Log.d(TAG, "onTimeout: eventId = " + eventId + ", eventType = " + eventType);
29
}
30
31
@Override
32
public boolean popupEventDecideShow(PopupWindowEvent popup, EventPopupDecisionAction decisionAction) {
33
34
String target = popup.getRule().getTarget();
35
Log.d(TAG, "popupEventDecideShow message name = " + popup.getName() + "target = " + target);
36
37
return false;
38
}
39
})
40
...
41
);
Copied!
如果您的popupEventDecideShow方法返回true的话,您必须手动实现弹窗的样式,并调用相关api手动触发弹窗的展示,点击或关闭事件。
1
public class EventPopupDecisionAction {
2
/// 弹窗展示、会发送展示事件
3
public void appeared();
4
/// 弹窗点击、会发送点击事件
5
public void clicked();
6
/// 弹窗关闭、会发送关闭事件
7
public void closed()
8
}
Copied!

5 设置弹窗SDK异常上传开关

弹窗SDK会收集SDK内部异常上报服务端,方便开发更好的追踪弹窗SDK的问题,和完善弹窗SDK的功能。如果您不想帮助我们弹窗产品完善功能,或者和您的crash收集框架有冲突,您可以选择关闭此功能。

5.1 setUploadExceptionEnable

弹窗异常消息上报开关
1
setUploadExceptionEnable(boolean uploadExceptionEnable)
Copied!

5.2 参数说明

参数名
类型
必填
默认值
说明
uploadExceptionEnable
boolean
true
开关SDK异常上传功能,true开启,false关闭

5.3 代码示例

1
GrowingTouch.startWithConfig(this, new GTouchConfig()
2
.setUploadExceptionEnable(true)
3
...
4
);
Copied!

6. 设置用户注册时间

版本要求:1.2.0及以上
您可以设置用户注册时间,这样就可以在做分群选择时使用注册至今来筛选用户。
使用上传登录用户变量接口上传用户注册时间,您需要将key设置为CreateAt。
1
GrowingIO.getInstance().setUserId("lisi");
2
// 登陆用户属性 注册至今 需设置CreateAt,值必须用YYYYMMDD 的方式上传,否则无法生效 要求SDK1.2.0及以上
3
GrowingIO.getInstance().setPeopleVariable("CreateAt","20191219");
Copied!

三、API介绍( GrowingTouch.class )

1 void setEventPopupEnable(boolean enable)

打开或关闭弹窗

2 void enableEventPopupAndGenerateAppOpenEvent()

打开弹窗并触发AppOpen事件。
应用场景时:担心弹窗SDK在APP启动的Logo页或者闪屏页显示弹窗,这时可以选择在初始化时关闭弹窗开关,然后在APP的内容页打开时再打开弹窗开关。
如果只是单纯调用`GrowingTouch.setEventPopupEnable(true)`只会打开弹窗开关,并不会触发AppOpen的弹窗事件。调用该API则会打开弹窗的同时触发一个AppOpen的弹窗事件。(AppOpen 对应的是触发时机选择“打开App时”)

3 boolean isEventPopupShowing()

弹窗是否正在显示

4 loadPopupWindowEvents()

回调形式获取到弹窗数据列表,您可以在此自定义一些弹窗样式。

4.1 代码示例

1
GrowingTouch.loadPopupWindowEvents(new CompletionCallback<List<PopupWindowEvent>>() {
2
@Override
3
public void onSuccess(List<PopupWindowEvent> result) {
4
if(result.size > 0){
5
PopupWindowEvent popup = result.get(0);
6
String target = popup.getRule().getTarget();
7
Log.d(TAG, "target = " + target+"message name = " + popup.getName());
8
}
9
}
10
11
@Override
12
public void onFailed(int errorCode, String description) {
13
Log.d(TAG, "error = " + errorCode);
14
}
15
16
});
Copied!

4.2 弹窗相关数据结构

1
public class PopupWindowEvent {
2
3
/// 消息唯一标识,客户端可以用来去重。
4
private int id;
5
/// 弹窗名称
6
private String name;
7
/// 代表弹窗消息的状态,activated:有效,其他状态都不显示。
8
private String state;
9
/// normal 类型的弹窗 html 地址,用 webView 加载。
10
private String content;
11
/// 优先级,数字越大优先级越高,如果优先级相同比较最后更新时间,最近更新的优先。
12
private int priority;
13
/// 最近更新时间。
14
private long updateAt;
15
/// 弹窗触发规则
16
private Rule rule;
17
/// A/B 测试
18
private AbTest abTest;
19
20
}
21
22
public class Rule {
23
24
/// 弹窗跳转内容
25
private String target;
26
/// 弹窗用户属性过滤规则
27
private RuleFilters filters;
28
/// 弹窗触发事件规则
29
private TriggerFilter triggerFilter;
30
/// 消息有效开始时间。暂时不生效,传任意时间
31
private long startAt;
32
/// 消息有效截止时间。暂时不生效,传任意时间
33
private long endAt;
34
/// 弹窗间隔时间
35
private long triggerCd;
36
/// 去重配置 (loop:点完之后满足一定条件会继续弹出;dispose:点击之后再也不弹)
37
private String clickMode;
38
/// 消息触发次数
39
private int limit;
40
41
}
42
43
public class RuleFilters {
44
45
/// 完整的条件表达式
46
private String expr;
47
/// 表达式的每个条件
48
private List<RuleExpr> exprs;
49
}
50
51
public class RuleExpr {
52
53
/// 符号
54
private String symbol;
55
/// 类型
56
private String type;
57
/// 事件标识符
58
private String key;
59
/// 运算符
60
private String op;
61
/// 值类型
62
private String valueType;
63
/// 运算结果
64
private List<String> values;
65
}
66
67
public class TriggerFilter {
68
69
/// 完整的条件表达式
70
private String conditionExpr;
71
/// 表达式的每个条件
72
private List<TriggerConditions> conditions;
73
}
74
75
public class TriggerConditions {
76
77
/// 过滤类型
78
private String type;
79
/// 别名
80
private String alias;
81
/// 事件标识符
82
private String key;
83
/// 事件类型 (system: 预定义事件、custom: 自定义事件)
84
private String measurementType;
85
/// 次数或者求和
86
private String aggregator;
87
/// 运算符
88
private String op;
89
/// 维度运算符
90
private String dimFiltersOp;
91
/// 额外属性
92
private String attribute;
93
/// 运算结果
94
private List<String> values;
95
/// 过滤维度
96
private List<DimFilters> dimFilters;
97
}
98
99
public class DimFilters {
100
101
/// 维度名称
102
private String dim;
103
/// 运算符
104
private String op;
105
/// 值类型
106
private String valueType;
107
/// 运算结果
108
private List<String> values;
109
}
110
111
public class AbTest {
112
/// 实验组的编号
113
private String dimension;
114
/// 当前的实验组(A组或B组)
115
private String symbol;
116
/// 控制组,YES:不要弹窗;NO: 需要弹窗
117
private boolean ctrlGroup;
118
}
Copied!

四、其他

1. 弹窗跳转原生Activity界面

若弹窗跳转链接为 GInApp://com.growingio.gtouch.InAppPageActivity?key1=value1&key2=value2 那么会打开原生界面 InAppPageActivity,并携带两个参数。
对应的Web弹窗页面配置如下图所示:
  • 弹窗Web页面配置截图如下:
其中「自定义参数」意思是输入任何您自己的scheme(自定义协议),
比如: myapp://productdetails/itemabc ,然后在onclick事件回调中解析出来就行了
1
@Override
2
protected void onCreate(Bundle savedInstanceState) {
3
super.onCreate(savedInstanceState);
4
setContentView(R.layout.activity_in_app_page);
5
Intent intent = getIntent();
6
Log.e(TAG, "onCreate: key1 = " + intent.getStringExtra("key1"));
7
Log.e(TAG, "onCreate: key2 = " + intent.getStringExtra("key2"));
8
}
Copied!

2. "打开APP时"事件触发的时机

打开APP时,无论是冷启动还是热启动,第一个Activity的onStart生命周期的时候触发。

3 okhttp 版本要求

需要升级到3.12.1,弹窗使用了新版的方法,否则会报错。
Last modified 5mo ago