资源位 SDK(Android)
最低兼Android版本4.2 API 17
资源位SDK主要提供两种接入方式:
  • 原生模板
在视图对应位置进行轮播图GTouchBanner的初始化,banner配置后调用轮播图API,数据请求、banner视图的样式、图片缓存、点击跳转行为等全部通过接口下发的配置在SDK内部处理
集成与使用代码参考 GIO电商demo shopping分支的HomeFragment文件
  • 自渲染
调用API接口GrowingTouch#loadBannerData获取banner数据模型以及响应信息,后续展示及点击逻辑由用户进行自实现

集成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依赖

v1.2.0之前的SDK升级到v1.2.0之后,若还想使用触达原生banner模板,必须集成以下相关依赖
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
//触达原生banner模板依赖
8
implementation "com.growingio.android.widget:gtouch-banner:$gtouch_version"
9
}
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
.setChannel("XXX应用商店")
9
);
10
11
GrowingTouch.startWithConfig(this, new GTouchConfig()
12
.setDebugEnable(BuildConfig.DEBUG)
13
);
14
}
15
}
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. 参数说明

v1.1.0之前使用了触达原生banner模板的SDK升级到v1.2.0之后必须修改布局文件里相关属性名,比如bannerKey改为gtouchBannerKey
配置字段
属性字段
是否必填
类型
说明
Bannerkey
gtouchBannerKey
string
在服务端进行查看后配置到本地,一个bannerKey对应一个banner(唯一标识),不设置抛出IllegalArgumentException
轮播间隔
gtouchAutoPlayInterval
long
不设置默认为3000ms,注意单位为ms
自动循环
gtouchAutoPlayAble
boolean
不设置默认为ture
轮播指示器样式
gtouchPointDrawable
ResourceId
不设置为SDK默认小圆点
轮播指示器位置
gtouchIndicatorGravity
int(Gravity)
默认为Gravity.CENTER_HORIZONTAL | Gravity.BOTTOM
默认占位图
gtouchPlaceholderDrawable
ResourceId
用户设置,不设置默认为-1
图片的填模式
scaleType
ImageView.ScaleType
不设置默认为CENTER_CROP
错位占位图
gtouchErorReplaceDrawable
ResourceId
用户设置,不设置抛出IllegalArgumentException

2. 在对应视图xml中添加Banner控件(建议使用xml布局)

1
<com.growingio.android.sdk.gtouch.widget.banner.GTouchBanner
2
android:id="@+id/gtouch_banner"
3
android:layout_width="match_parent"
4
android:layout_height="107dp"
5
app:gtouchBannerKey="99299c5d32d6e14a"
6
app:gtouchErrorReplaceDrawable="@mipmap/load_error"
7
app:gtouchIndicatorGravity="bottom|right"
8
app:gtouchPlaceholderDrawable="@mipmap/loading" />
Copied!

3. GTouchBanner初始化代码如下

1
private GTouchBanner mGTouchBanner;
2
mGTouchBanner = findViewById(R.id.gtouch_banner);
3
mGTouchBanner.loadData(new BannerStateChangedListener() {
4
/**
5
* Banner数据加载成功
6
*
7
* @param banner Banner控件对象
8
*/
9
@Override
10
public void onLoadDataSuccess(GTouchBanner banner) {
11
Log.e(TAG, "onLoadDataSuccess: ");
12
}
13
14
15
/**
16
* Banner数据加载失败
17
*
18
* @param banner Banner控件对象
19
* @param errorCode 错误码
20
* @param description 错误描述,有可能为null
21
*/
22
@Override
23
public void onLoadDataFailed(GTouchBanner banner, int errorCode, String description) {
24
Log.e(TAG, "onLoadDataFailed: errorCode = " + errorCode + ", description = " + description);
25
}
26
27
28
/**
29
* Banner item被点击
30
*
31
* @param banner Banner控件对象
32
* @param position item所处位置
33
* @param targetUrl 需要跳转的路由url
34
* @return 返回为true,资源位SDK不在处理跳转的路由url;返回为false,资源位SDK会处理跳转内部界面和H5两种资源位系统提供的路由
35
*/
36
@Override
37
public boolean onItemClick(GTouchBanner banner, int position, String targetUrl) {
38
Log.e(TAG, "onItemClick: position = " + position + ", targetUrl = " + targetUrl);
39
return false;
40
}
41
42
/**
43
* 加载失败图片被点击
44
*
45
* @param banner Banner控件对象
46
*/
47
@Override
48
public void onErrorImageClick(GTouchBanner banner) {
49
Log.e(TAG, "onErrorImageClick");
50
}
51
});
Copied!

自渲染接入

1. 数据模型说明

  • BannerData
属性字段
类型
说明
getName()
string
bannerd名称
getBannerkey()
string
banner的唯一标识
getItem()
List<BannerItemData>
banner的所有item,类型为bannerItemData
  • BanneritemData
属性字段
类型
说明
getIndex()
int
index标识,从0开始
getTitle()
string
item的名称
getImageUrl()
string
bannerItem显示图片url

2. 获取banner数据模型

使用GrowingTouch#loadBannerData(@NonNull String bannerKey,@NonNull final BannerDataCallback callback)
v1.3.0版本新增了对灵活资源位的支持,注意灵活资源位可能发生没有banner的情况,需要特殊处理。
1
// bannerKey在服务端进行查看后配置到本地
2
GrowingTouch.loadBannerData("9e38f09a9cc50a79", new BannerDataCallback() {
3
/**
4
* Banner数据请求成功
5
*
6
* @param bannerData Banner所有数据
7
*/
8
@Override
9
public void onSuccess(BannerData bannerData) {
10
if(bannerData.getItems().size < 1){
11
throw new GTouchSDKException("灵活资源位会发生item为0的情况,需特殊处理")
12
}
13
}
14
15
16
/**
17
* Banner数据请求失败
18
*
19
* @param errorCode 错误码
20
* @param description 错误描述,有可能为null,如网络错误时
21
*/
22
@Override
23
public void onLoadFailed(int errorCode, String description) {
24
}
25
});
Copied!

3. bannerItem绑定对应的itemview的点击事件

使用BannerItemData#bindItemDataToClickView(final View clickView, final BannerItemOnClickListener listener)
1
// itemView即每个bannerItemData对应的视图
2
bannerItemData.bindItemDataToClickView(itemView, new BannerItemOnClickListener() {
3
/**
4
* 点击回调
5
*
6
* @param clickView 点击的View
7
* @param itemData 点击的Item的数据
8
* @param targetUrl 需要跳转的目标Url
9
* targetUrl两种格式分别为:
10
* 1.直接的网址(如:https://www.growingio.com)
11
* 2.跳转应用内部界面(如:GInApp://com.growingio.gtouch.InAppPageActivity?key1=value1&key2=value2),在自渲染中跳转需要用户进行处理
12
*/
13
@Override
14
public void onClick(View clickView, BannerItemData itemData, String targetUrl) {
15
}
16
});
17
Copied!
使用bannerItem进行绑定点击事件的原因及注意事项:
  • 添加额外依赖:com.android.support:viewpager:x.x.x(含有该依赖即可,如依赖包:com.android.support:appcompat-v7:x.x.x)
  • 使用androidx时请同时设置android.enableJetifier为true
  • 保证banner的展示以及点击事件能够正确传给GroiwngIO的数据端,需要使用BannerItemData#bindItemDataToClickView进行点击事件的绑定
  • 将对应视图的点击事件实现在BannerItemOnClickListener回调时,不要进行额外的点击事件设置
  • 保证banner的展示事件准确,需要在视图真正显示时进行BannerItemData#bindItemDataToClickView调用,注意如使用ViewPager存在预加载(无法disable),建议在类似PagerAdapter#setPrimaryItem函数中进行绑定调用
  • 如使用ViewPager2(目前版本:androidx.viewpager2:viewpager2:1.0.0-beta03),为保证展示事件的准确性建议关闭离屏加载(类似ViewPager的预加载,默认关闭),使用预加载时在视图绑定时(在创建时将导致展示事件错乱)进行BannerItemData#bindItemDataToClickView调用

原生模板接入异常情况说明

1. 获取Banner数据失败(包括获取到的BannerItem的size为0)

  • 当存在上一次获取到Banner数据时,将会加载上一次数据
  • 没有上一次数据时,将会回调用户错误(onLoadDataFailed)并加载设置的错误图片
  • 获取到的BannerItem的size为0时,原生模板所在的view会自动隐藏,界面上会有对应的隐藏动画,请开发者酌情考虑使用我们的模板。

2. 后端返回的配置数据banneritem的index不连续(包括:自渲染接入)

SDK中会将index进行去重并重新编号

3. BannerItem单张图加载失败

删除该item,删除后不存在item将会加载用户与设置的错误图片(errorReplaceDrawable)
Last modified 5mo ago