> For the complete documentation index, see [llms.txt](https://growingio.gitbook.io/mp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://growingio.gitbook.io/mp/developers/integrations/android-sdk/banner-component.md).

# 资源位 SDK（Android）

{% hint style="info" %}
最低兼Android版本4.2 API 17
{% endhint %}

资源位SDK主要提供两种接入方式：

* 原生模板

在视图对应位置进行轮播图GTouchBanner的初始化,banner配置后调用轮播图API，数据请求、banner视图的样式、图片缓存、点击跳转行为等全部通过接口下发的配置在SDK内部处理

集成与使用代码参考 [GIO电商demo](https://github.com/growingio/AndroidDemo) shopping分支的HomeFragment文件

* 自渲染

调用API接口GrowingTouch#loadBannerData获取banner数据模型以及响应信息,后续展示及点击逻辑由用户进行自实现

## 集成SDK

### 1. 集成GrowingIO Android无埋点SDK

添加资源位 SDK前请确保您已经集成了我们公司的埋点 SDK，版本需要在 2.6.9 及以上，详细情况请移步[Android埋点SDK帮助文档](https://docs.growingio.com/v3/developer-manual/sdkintegrated/android-sdk/manunl-android-sdk)。最低兼容的 Android 版本为 4.2 。

### 2. 添加依赖

{% hint style="info" %}
1.5.0版本后仓库从JCenter迁移到了Maven Central, 请使用mavenCentral()替换jcenter()
{% endhint %}

#### 2.1 在app build.gradle添加SDK依赖

{% hint style="info" %}
v1.2.0之前的SDK升级到v1.2.0之后，若还想使用触达原生banner模板，必须集成以下相关依赖
{% endhint %}

```java
dependencies {
    ...
    //由于资源位底层网络库依赖OkHttp3网络库，请添加OkHttp3依赖
    implementation "com.squareup.okhttp3:okhttp:3.12.1"
    //资源位SDK依赖
    implementation "com.growingio.android:gtouch:$gtouch_version"
    //触达原生banner模板依赖
    implementation "com.growingio.android.widget:gtouch-banner:$gtouch_version"
}
```

> $gtouch\_version 为资源位SDK版本号，现最新的版本号为请参考[SDK更新日志](/mp/developers/integrations/changelog.md)。

###  3. 需要的权限列表

所需权限同无埋点SDK

```java
<uses-permission android:name="android.permission.INTERNET" />
<!--非危险权限，不需要运行时请求，Manifest文件中添加即可-->
<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" />
```

### 4. 初始化SDK

请将以下`GrowingTouch.startWithConfig`加在您的Application 的 `onCreate` 方法中，且保证在埋点SDK初始化代码`GrowingIO.startWithConfiguration`后

```java
public class MyApplication extends Application {
​
    @Override
    public void onCreate() {
        super.onCreate();
        GrowingIO.startWithConfiguration(this, new Configuration()
            .trackAllFragments()
            .setChannel("XXX应用商店")
            );

        GrowingTouch.startWithConfig(this, new GTouchConfig()
             .setDebugEnable(BuildConfig.DEBUG)
             );
    }
}
```

### 6. 代码混淆

如果您启用了代码混淆，请务必在您的proguard-rules.pro文件里加入下面的代码：

```java
#GrowingIO
-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$**{
	*;
}

#okhttp
-dontwarn okhttp3.**
-keep class okhttp3.**{*;}

#okio
-dontwarn okio.**
-keep class okio.**{*;}
```

## 原生模板接入

### 1. 参数说明

{% hint style="info" %}
v1.1.0之前使用了触达原生banner模板的SDK升级到v1.2.0之后必须修改布局文件里相关属性名，比如bannerKey改为gtouchBannerKey
{% endhint %}

| 配置字段      | 属性字段                      | 是否必填 | 类型                   | 说明                                                                       |
| --------- | ------------------------- | ---- | -------------------- | ------------------------------------------------------------------------ |
| 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布局）

```swift
<com.growingio.android.sdk.gtouch.widget.banner.GTouchBanner
    android:id="@+id/gtouch_banner"
    android:layout_width="match_parent"
    android:layout_height="107dp"
    app:gtouchBannerKey="99299c5d32d6e14a"
		app:gtouchErrorReplaceDrawable="@mipmap/load_error"
		app:gtouchIndicatorGravity="bottom|right"
		app:gtouchPlaceholderDrawable="@mipmap/loading" />
```

### 3. GTouchBanner初始化代码如下

```swift
private GTouchBanner mGTouchBanner;
mGTouchBanner = findViewById(R.id.gtouch_banner);
mGTouchBanner.loadData(new BannerStateChangedListener() {
    /**
     * Banner数据加载成功
     *
     * @param banner Banner控件对象
     */
    @Override
    public void onLoadDataSuccess(GTouchBanner banner) {
        Log.e(TAG, "onLoadDataSuccess: ");
    }


    /**
     * Banner数据加载失败
     *
     * @param banner Banner控件对象
     * @param errorCode 错误码
     * @param description 错误描述，有可能为null
     */
    @Override
    public void onLoadDataFailed(GTouchBanner banner, int errorCode, String description) {
        Log.e(TAG, "onLoadDataFailed: errorCode = " + errorCode + ", description = " + description);
    }


    /**
     * Banner item被点击
     *
     * @param banner Banner控件对象
     * @param position item所处位置
     * @param targetUrl 需要跳转的路由url
     * @return 返回为true，资源位SDK不在处理跳转的路由url；返回为false，资源位SDK会处理跳转内部界面和H5两种资源位系统提供的路由
     */
    @Override
    public boolean onItemClick(GTouchBanner banner, int position, String targetUrl) {
        Log.e(TAG, "onItemClick: position = " + position + ", targetUrl = " + targetUrl);
        return false;
    }

    /**
     * 加载失败图片被点击
     *
     * @param banner Banner控件对象
     */
    @Override
    public void onErrorImageClick(GTouchBanner banner) {
        Log.e(TAG, "onErrorImageClick");
    }
});
```

## 自渲染接入

### 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的情况，需要特殊处理。

```swift
// bannerKey在服务端进行查看后配置到本地
GrowingTouch.loadBannerData("9e38f09a9cc50a79", new BannerDataCallback() {
    /**
     * Banner数据请求成功
     *
     * @param bannerData Banner所有数据
     */
    @Override
    public void onSuccess(BannerData bannerData) {
          if(bannerData.getItems().size < 1){
              throw new GTouchSDKException("灵活资源位会发生item为0的情况，需特殊处理")
          }
    }


    /**
     * Banner数据请求失败
     *
     * @param errorCode 错误码
     * @param description 错误描述，有可能为null，如网络错误时
     */
    @Override
    public void onLoadFailed(int errorCode, String description) {
    }
});
```

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

使用BannerItemData#bindItemDataToClickView(final View clickView, final BannerItemOnClickListener listener)

```swift
// itemView即每个bannerItemData对应的视图
bannerItemData.bindItemDataToClickView(itemView, new BannerItemOnClickListener() {
    /**
     * 点击回调
     *
     * @param clickView 点击的View
     * @param itemData 点击的Item的数据
     * @param targetUrl 需要跳转的目标Url
     * targetUrl两种格式分别为:
     * 1.直接的网址(如:https://www.growingio.com)
     * 2.跳转应用内部界面(如:GInApp://com.growingio.gtouch.InAppPageActivity?key1=value1&key2=value2),在自渲染中跳转需要用户进行处理  
     */
    @Override
    public void onClick(View clickView, BannerItemData itemData, String targetUrl) {
    }
});

```

{% hint style="info" %}
使用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调用
  {% endhint %}

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

#### **1. 获取Banner数据失败（包括获取到的BannerItem的size为0）**

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

#### **2. 后端返回的配置数据banneritem的index不连续（包括：自渲染接入）**

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

#### **3. BannerItem单张图加载失败**

删除该item，删除后不存在item将会加载用户与设置的错误图片（errorReplaceDrawable）


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://growingio.gitbook.io/mp/developers/integrations/android-sdk/banner-component.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.