You need to enable JavaScript to run this app.
导航

Android SDK集成

最近更新时间2023.11.27 11:18:39

首次发布时间2022.07.12 11:06:45

一、简介

GMP 资源位 SDK 是 GMP 对外提供的资源位数据管理的 SDK 。
资源位 SDK 主要提供两种接入方式:

  • 自渲染

用户调用 API 接口,获取 GMP 资源位配置数据,自行处理视图渲染、交互监听,在交互变化时通知 SDK。

  • SDK 渲染

SDK 内部完成一系列流程,包括 请求配置、数据处理、视图渲染(banner 视图的样式)、图片缓存、交互监听、事件上报。

二、SDK 集成

1. 配置应用鉴权信息

需提供 Android 应用包名和应用签名然后在 GMP 后台配置(管理中心-消息管理-客户端SDK-鉴权配置),需保证与 app 的实际信息一致,可联系您的客户端开发人员获取。该项配置用于接口的安全鉴权校验,不会用于其他用途。
示例如下:

# Android包名
com.gmp.demo

# 获取Android应用签名 SHA256 fingerprint
12:9F:EE:EC:6B:8A:DA:77:35:13:D8:7B:BC:A8:F4:74:71:4D:95:6C:ED:91:9B:9E:18:B7:9A:BE:4E:45:B7:EF

然后到GMP后台配置相关信息
alt

alt

2. 集成 SDK

注意

资源位 SDK 集成 Demo,可参考 https://www.volcengine.com/docs/6315/1130446
Demo 需要在 Config.kt 文件配置对应的参数才能获取到对应的数据

2.1 集成 Finder SDK

资源位 SDK 依赖 Finder SDK 进行数据回流,在使用资源位 SDK 前,请确保已经集成了 Finder SDK。并且 Finder SDK 版本在 6.16.1 及以上。
如果使用多 module,请确保资源位 SDK 的 module 能引用到 Finder SDK 。

Finder Android SDK接入指南

2.2 集成资源位 SDK

Gradle 引入方式(推荐)

接入资源位 SDK,在 gradle 中添加依赖

  • Gradle 7.0 以下
// 在 project 级别的 build.gradle 中添加 maven 仓库
// 在 allprojects 的 repositories 中添加 maven 仓库
allprojects {
    repositories {
        maven {
            url 'https://artifact.bytedance.com/repository/Volcengine/'
        }
        // 其他仓库
    }
}
  • Gradle 7.0 及以上
// 在 project 级别的 setting.gradle 中添加 maven 仓库
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        // 省略其他
        maven{
            url 'https://artifact.bytedance.com/repository/Volcengine/'
        }
    }
}
  • 引入 SDK
//在app:build.gradle下添加
dependencies {
    // 最新版本请查看版本记录获取
    implementation 'com.bytedance.gmp:gmp_reach:${[new_version]}'

    // SDK 版本 >= 2.1.1 不需引入
    // 可替换为实际接入的 okhttp 版本,但最好使用该版本避免兼容性问题
    implementation "com.squareup.okhttp3:okhttp:3.12.4"
}

手动引入方式

推荐您远程引入SDK。如特殊情况需要手动引入,请补充阅读本小节。

请在 Android 弹窗、资源位SDK 版本记录 下载对应版本文件

文件解压后需要把所有 aar,都添加到 libs 目录下

注意

SDK 版本 < 2.1.1 , 手动引入弹窗SDK aar 之后,记得要引入 okhttp3

implementation fileTree(dir: 'libs', include: ['*.jar','*.aar'])


// SDK 版本 >= 2.1.1 不需引入
// 可替换为实际接入的 okhttp 版本,但最好使用该版本避免兼容性问题
implementation "com.squareup.okhttp3:okhttp:3.12.4"

3.3 权限设置

<!--在AndroidManifest.xml中配置 -->
<uses-permission android:name="android.permission.INTERNET"/>

3 初始化 SDK

3.1 获取初始化必备id

3.1.1 获取项目id和应用id

在gmp首页,点击右上角头像-项目管理,即可进入项目后台页查看对应项目的项目id和应用id(项目id是初始化资源位sdk的appid,应用id是用于初始化Finder SDK的appid)

3.1.2 获取主账号id(Saas版本)

进入火山引擎控制台,点击右上角头像 icon,红框中的账号 ID 即是 主账号id

3.2 初始化

3.2.1 初始化(私有化版本)

首先您需要初始化 Finder SDK,具体可参考:初始化 Finder SDK (私有化版本) - 火山引擎,再初始化资源位 SDK

注意

资源位SDK 要在 Application 类的 onCreate() 方法主进程主线程初始化。
资源位SDK 请在 Application 中初始化,如果您的app中涉及隐私弹窗协议,请正确配置 setAutoStart() 并且在同意隐私协议之后调用 GMPResourceSDK.start()

GMP 域名为私有化部署域名 , 默认为 https://xxxxxx.com 。
如果租户名不为 gmp ,则需要拼接租户名,如: https://xxxxxx.com/gmpa

示例代码如下:

// Application
public void onCreate() {
		// Finder SDK 不需要区分进程,务必在多个进程都初始化
	  initAppLog();
    // 弹窗、资源位 SDK 初始化只需要在主进程初始化既可 —— 2.1.0.5-bugfix 及以上内部已经判断,外部可不需要判断
    if (ToolUtils.isMainProcess(this)) {
	      // 生成触达相关的配置(必选)
	      ReachConfig reachConfig = initReachConfig();
	      // 初始化 资源位SDK
	      initGMPResourceSDK(reachConfig);
    }
}

private ReachConfig initReachConfig() {
		return new ReachConfig.Builder()
				// 设置 gmp 项目id
        .setAppId(Config.INSTANCE.getGmpAppId())
        .setAppConfig(new IAppConfig() {
		         @NonNull
		         @Override
		         public String getHost() {
				         // 设置 GMP 的域名
		             return Config.INSTANCE.getGmpHost();
		         }
        })
        // 如果项目支持自动登录,用户画像已经存在,需要提前设置上
        .setUniqueUid(uuid)
        .setUniqueUidType(uuidType)
        //用于图片类型的加载,可以根据接口说明自行选择图片加载库;SDK版本 >= 2.1.1 已经废除,无须实现
        .setImageConfig(MyImageConfig.INSTANCE.getMyImageConfig())
        .build();
}

private void initGMPResourceSDK(ReachConfig reachConfig) {
			ResourceConfig.Builder b = new ResourceConfig.Builder()
                      .setReachConfig(reachConfig)
                      // 该 api 在 2.1.0 已经移除 , 旧版本 clientId 传入任意值即可
                      .setClientId("");
      // 是否已经同意了隐私协议,如果未同意,请传 false              
      if (!PrivacyAgreementHelper.INSTANCE.allowPrivacyAgreement()) {
            b.setAutoStart(false);
            // 请在隐私弹窗同意之后务必调用 GMPResourceSDK.INSTANCE.start()
      }
      GMPResourceSDK.INSTANCE.initResource(
              this,
              b.build()
      );
}


3.3.2 初始化(Saas版本)

首先您需要初始化 Finder SDK,具体可参考:初始化 Finder SDK (Saas版本) - 火山引擎,再初始化资源位 SDK

Saas GMP Host 为:https://gmp-saas-api.console.volcengine.com

注意

资源位SDK 要在 Application 类的 onCreate() 方法主进程主线程初始化。
资源位SDK 请在 Application 中初始化,如果您的app中涉及隐私弹窗协议,请正确配置 setAutoStart() 并且在同意隐私协议之后调用 GMPResourceSDK.start()

class Application{
    //Application
    public void onCreate() {
		    // Finder SDK 不需要区分进程,务必在多个进程都初始化
			  initAppLog();
		    // 弹窗、资源位 SDK 初始化只需要在主进程初始化既可—— 2.1.0.5-bugfix 及以上内部已经判断,外部可不需要判断
        if (ToolUtils.isMainProcess(this)) {
            // 生成触达相关的配置(必选)
            ReachConfig reachConfig = initReachConfigSaas();
            // 初始化 资源位SDK
            initGMPResourceSDK(reachConfig);
        }
    }

    private ReachConfig initReachConfigSaas() {
        // 生成触达相关的配置(必选)
        return new ReachConfig.Builder()
                // 设置 gmp 项目id
                .setAppId(Config.INSTANCE.getGmpAppId())
                .setAppConfig(new IAppConfig() {
                    @NonNull
                    @Override
                    public String getHost() {
                        // 设置 gmp saas 的域名
                        return "https://gmp-saas-api.console.volcengine.com";
                    }
                })
                // 设置 gmp 主账号id
                .setMainAccountId(Config.INSTANCE.getGmpMainAccountId())
                // 如果项目支持自动登录,用户画像已经存在,需要提前设置上
				        .setUniqueUid(uuid)
				        .setUniqueUidType(uuidType)
                //用于图片类型的加载,可以根据接口说明自行选择图片加载库;SDK版本 >= 2.1.1 已经废除,无须实现
                .setImageConfig(MyImageConfig.INSTANCE.getMyImageConfig())
                .build();
    }

    private void initGMPResourceSDK(ReachConfig reachConfig) {

	    ResourceConfig.Builder b = new ResourceConfig.Builder()
                      .setReachConfig(reachConfig)
                      // 该 api 在 2.1.0 已经移除 , 旧版本 clientId 传入任意值即可
                      .setClientId("");
      // 是否已经同意了隐私协议,如果未同意,请传 false              
      if (!PrivacyAgreementHelper.INSTANCE.allowPrivacyAgreement()) {
            b.setAutoStart(false);
            // 请在隐私弹窗同意之后务必调用 GMPResourceSDK.INSTANCE.start()
      }
      GMPResourceSDK.INSTANCE.initResource(
              this,
              b.build()
      );
    }
};
    
    

3.2.3 参数详情

下面必填项需确保正确传入 SDK,SDK 内部在初始化会进行校验,所有配置缺失则 SDK 内部会抛出异常。

  • ReachConfig 详细配置如下

    参数类型是否必填描述
    debugboolean切换 debug 模式,默认为 false,开启则会打印内部日志
    appIdstringGMP 项目ID,可根据3.1.1指引获取
    appConfiginterface配置请求域名
    threadConfiginterface配置线程池策略 [详细见4.2]
    ImageConfiginterface配置自定义的图片加载接口,SDK版本 >= 2.1.1 已经废除,无须实现[详细见3.3]
    uniqueUidstring用户画像id,存在用户画像时传入
    uniqueUidTypestring用户画像id类型,存在用户画像时传入
    UbaConfiginterface配置其他平台uba配置 [详细见4.3]
    mainAccountIdstringsaas版本的主账号id,接入saas版本必须传入
    finderInitConfigFinderInitConfig设置finder配置,如无特殊需求可不传入
    enableRetryWhenServerErrorboolean设置当服务器请求失败后是否会自动重试(默认开启
  • 资源位SDK 详细配置如下

参数类型是否必填描述
reachConfigReachConfig触达配置
resourceCacheLevelenum设置资源位缓存等级[详细见4.1]
autoStartboolean设置是否自动启动,如果隐私协议未同意请传 false

3.3 图片加载接口说明(SDK版本 >= 2.1.1 已经废除,无须实现)

资源位 SDK 需要业务实现图片加载接口,以便于 SDK 内部能正常加载图片
IImageConfig 接口 定义如下:

/**
 * 图片加载接口
 */
interface IImageConfig {
    /**
     * 获取 url 的图片 , 然后根据实际大小 通过 listen 返回
     *
     * @param viewWidth  图片View的宽度
     * @param viewHeight 图片View的高度
     * @param url        加载的 url
     * @param listener   回调 listener , 务必正确回调 listener 的 onSucceed 与 onFail
     */
    void getImage(int viewWidth, int viewHeight, String url, IImageListener listener);

    /**
     * 预加载图片业务可以自定义加载级别(到磁盘还是内存)
     * @param url 图片 url
     */
    void preloadImage(String url);

    /**
     * 检查图片是否在缓存中
     * @param uri 图片 uri
     */
    boolean isInMemoryOrDiskCache(Uri uri);

    //加载图片回调
    interface IImageListener {
        /**
         * 成功时回调加载后的 bitmap
         * @param bitmap 加载成功的 bitmap
         */
        void onSucceed(Bitmap bitmap);

        /**
         * 失败时回调错误信息
         * @param throwable 加载失败的异常
         */
        void onFail(Throwable throwable);
    }
}

图片加载接口示例

文档中给出了一种基于 Fresco 的图片加载实现,接入方可以根据自己实际使用的图片加载库实现该接口

在 gradle 中引入 Fresco 并在 application oncreate 中初始化 fresco
// Application
public void onCreate() {
		Fresco.initialize(context);
}
// 实现接口 IImageConfig
public class FrescoImageConfigJava implements IImageConfig {
    @Override
    public boolean isInMemoryOrDiskCache(Uri uri) {
        ImagePipeline imagePipeline = Fresco.getImagePipeline();
        return imagePipeline.isInBitmapMemoryCache(uri) || imagePipeline.isInDiskCacheSync(uri);
    }

    @Override
    public void getImage(int viewWidth, int viewHeight, String url, IImageListener imageListener) {
        ImageRequest imageRequest = ImageRequest.fromUri(Uri.parse(url));
        DataSource<CloseableReference<CloseableImage>> dataSource = Fresco.getImagePipeline().fetchDecodedImage(imageRequest, null);
        dataSource.subscribe(new BaseBitmapDataSubscriber() {
            @Override
            protected void onNewResultImpl(@Nullable Bitmap bitmap) {
                if (bitmap == null) {
                    imageListener.onFail(new Throwable("bitmap empty"));
                    return;
                }
                float scaleSize = getScaleSize(bitmap, viewWidth, viewHeight);
                imageListener.onSucceed(Bitmap.createScaledBitmap(bitmap, (int) (bitmap.getWidth() / scaleSize), (int) (bitmap.getHeight() / scaleSize), false));
            }

            @Override
            protected void onFailureImpl(DataSource<CloseableReference<CloseableImage>> dataSource) {
                imageListener.onFail(dataSource.getFailureCause());
            }
        }, CallerThreadExecutor.getInstance());
    }

    @Override
    public void preloadImage(String url) {
        if (url.isEmpty() || isDownloaded(Uri.parse(url))) {
            return;
        }
        ImageRequest imageRequest = ImageRequest.fromUri(Uri.parse(url));
        Fresco.getImagePipeline().prefetchToDiskCache(imageRequest, null);
    }

    private float getScaleSize(Bitmap bitmap, int viewWidth, int viewHeight) {
        float scaleWidth = bitmap.getWidth() / (viewWidth * 1.0f);
        float scaleHeight = bitmap.getHeight() / (viewHeight * 1.0f);
        return Math.max(scaleWidth, scaleHeight);
    }

    private boolean isDownloaded(Uri uri) {
        ImageRequest imageRequest = ImageRequest.fromUri(uri);
        if (imageRequest == null) {
            return false;
        }
        CacheKey cacheKey = Fresco.getImagePipeline().getCacheKeyFactory()
                .getEncodedCacheKey(imageRequest, null);
        return ImagePipelineFactory.getInstance()
                .getMainFileCache().hasKey(cacheKey);
    }
}



3.4 更新用户画像

如您的产品中有账户体系,请在用户登录后立即设置 uuid,以保证用户登录前后口径一致性。Finder SDK 登陆态变化可参考:Finder SDK 登陆态变化

除此之外,您还需要及时通知资源位SDK用户画像的变化

警告

在SDK版本 >= 2.1.0 之后,更新用户画像只能通过手动更新,旧版升级上来的请改成手动更新模式
注意 : 务必在 AppLog.setUserUniqueID 设置前调用手动更新

2.1.0 以下版本需要为 ReachConfig 增加以下配置:

private ReachConfig initReachConfig() {
		FinderInitConfig finderConfig = new FinderInitConfig.Builder()
								// 设置自动更新为关闭
                .setAutoUpdateUser(false)
                .build();
		return new ReachConfig.Builder()
				// ...省略其他配置...
				// 关闭自动更新
				.setFinderInitConfig(finderConfig)
        .build();
}


以下配置在各个SDK版本均要配置

// 手动更新用户画像,需要在合适的时机及时调用,如账号切换
// 更新资源位SDK用户画像,务必在 AppLog.setUserUniqueID 设置前调用   
GMPResourceSDK.INSTANCE.start(); // setAutoStart 为 false 时,需要调用
GMPResourceSDK.INSTANCE.updateUUid(Config.INSTANCE.getGmpUuid(),Config.INSTANCE.getGmpUuIdType());
// 更新 FinderSDK uuid
AppLog.setUserUniqueID(Config.INSTANCE.getGmpUuid(), Config.INSTANCE.getGmpUuIdType());


4 其他可选配置

4.1 设置资源位缓存等级

说明

资源位SDK内置了兜底缓存 & 用户缓存的双重缓存逻辑 (兜底缓存为gmp前端配置的兜底素材,用户缓存为上一次拉取该资源位id返回的素材),其中用户缓存优先级大于兜底缓存,在网络异常gmp服务端异常时会读取本地缓存或兜底素材作为对应资源位id的返回,如果接入方本身具有兜底能力可以在接入时设置资源位的缓存等级

参数说明

缓存等级策略
ResourceCacheLevel.NONE_CACHE不开启缓存
ResourceCacheLevel.DEFAULT_RESOURCE_CACHE只开启兜底缓存(GMP前端配置的兜底素材)
ResourceCacheLevel.LAST_REQUEST_CACHE只开启用户缓存(缓存上一次请求的素材)
ResourceCacheLevel.ALL_CACHE开启所有缓存,若不设置缓存等级,默认使用此策略
GMPResourceSDK.INSTANCE.initResource(
        this,
        new ResourceConfig.Builder()
        // 省略其他配置.....
        // 设置资源位SDK缓存等级
        .setResourceCacheLevel(ResourceCacheLevel.ALL_CACHE)
        .build()
        );


4.2 线程调度配置

支持在初始化 ReachConfig 中设置 IThreadConfig 用于管理线程调度

可以实现这个接口用于管理线程,SDK 中提供了线程池作为默认实现

java:

interface IThreadConfig{
		// 主线程 handler
    Handler getMainHandler();
	  // 子线程 handler
    Handler getBackgroundHandler();
}
new ReachConfig.Builder()
        // 省略其他配置.....
        // 接口实现参考例子,请按照项目中实际配置
        // 设置线程调度策略 , 可以配置项目自己的线程池 , 防止后台过多线程执行
        .setThreadConfig(new IThreadConfig() {
            @NonNull
            @Override
            public Handler getMainHandler() {
                return new Handler(Looper.getMainLooper());
            }

            @NonNull
            @Override
            public Handler getBackgroundHandler() {
                HandlerThread ht = new HandlerThread("BackgroundHandler");
                ht.start();
                return new Handler(ht.getLooper());
            }
        })
        .build();


4.3 其他平台uba配置

若使用 Finder SDK 进行数据上报,则无需关注此部分。若确认不使用 Finder SDK 上报数据,而是使用自己的 UBA 库进行数据上报,则需要实现 IUBAConfig 接口并初始化注入到 SDK 中。

4.3.1 实现 IUBAConfig 接口

IUBAConfig 接口定义 如下

public interface IUBAConfig {
    /**
     * 获取设备id(设备唯一标识)
     * @return
     */
    @NonNull
    String getDid();

    /**
     * 获取基准id(用户唯一标识)
     * @return
     */
    @NonNull
    String getBaseId();

    /**
     * 上报事件
     * @param eventName 事件名
     * @param jsonObject 事件属性
     * @return
     */
    void onEvent(@NotNull String eventName, @NotNull JSONObject jsonObject);

    /**
     * 获取AB实验参数
     * Params:
     * @param abKey - 实验标识
     * @param defaultValue - 默认值
     * @return 实验参数
     */
    @Nullable
    Object getABConfig(@NotNull String abKey, Object defaultValue);

    /**
     * 获取 Uba 的通参
     * @return 
     */
    @Nullable
    JSONObject getUbaCommonParams();
}

4.3.1 设置 UBAConfig

new ReachConfig.Builder()
        // 省略其他配置.....
        // 设置项目用到的 uba 系统, 默认接入为 finder
        .setUbaConfig(new IUBAConfig() {
            @NonNull
            @Override
            public String getDid() {
                return "";
            }

            @NonNull
            @Override
            public String getBaseId() {
                return "";
            }

            @Override
            public void onEvent(@NonNull String s, @NonNull JSONObject jsonObject) {

            }

            @Nullable
            @Override
            public <T> T getABConfig(@NonNull String s, T t) {
                return null;
            }

	          @Nullable
            @Override
            public JSONObject getUbaCommonParams() {
                return null;
            }
        })
        // 设置 debug 输出日志
        .debug(true)
        .build();


5 合规处理(隐私政策初始化的处理)

资源位SDK 务必请在 Application 中初始化,如果您的app中涉及隐私弹窗协议,请正确配置 资源位SDK 的初始化。

new ResourceConfig.Builder()
      // ...... 省略其他配置
      // 未同意隐私协议前传入 false , 同意传入 true
			.setAutoStart(false)
      .build()

然后在同意了隐私协议之后务必调用

GMPResourceSDK.INSTANCE.start()
三、SDK渲染方式接入资源位

1. Banner

1.1 参数说明

字段说明类型
autoScrollTimeInterval轮播时间间隔,单位为秒(s),默认为5sfloat
autoScroll自动轮播,默认TRUEboolean
currentPageIndicatorImagepageControl 选中时的图片,默认圆点reference
normalPageIndicatorImagepageControl 未选中时的图片,默认圆点reference
currentPageIndicatorColor非图片模式pageControl 选中的颜色,默认白色color
normalPageIndicatorColor非图片模式pageControl 未选中的颜色,默认灰色color
normalIndicatorWidthpageControl 未选中时的宽,默认6dimension
normalIndicatorHeightpageControl 未选中时的高,默认6dimension
currentIndicatorWidthpageControl 选中时的宽,默认6dimension
currentIndicatorHeightpageControl 选中时的高,默认6dimension
pageIndicatorSpacingpageControl 间距大小,默认6dimension
isShowPageControl是否显示pageControl,默认TRUEboolean

imageViewContentMode

作用于图片类型资源位,包括轮播图以及没有轮播图时的背景图
图片的填充模式,默认值 FIT_CENTER
可选项:

  • CENTER
  • CENTER_CROP
  • CENTER_INSIDE
  • FIT_XY
  • FIT_START
  • FIT_CENTER
  • FIT_END
  • MATRIX

enum

placeHolderImage轮播视图为空的默认错误占位图,默认使用SDK内部占位图reference

fontSize

作用于文字资源位类型
文字大小,默认12

dimension

fontColor

作用于文字资源位类型
文字颜色,默认黑色

color

1.2 在对应视图 xml 中添加 Banner 控件

<com.bytedance.gmpreach.resource.banner.ResourceView
    android:id="@+id/resource_view"
    android:layout_width="match_parent"
    android:layout_height="100dp"
    app:currentIndicatorHeight="10dp"
    app:currentIndicatorWidth="10dp"
    app:autoScrollTimeInterval="1.5"
    app:imageViewContentMode="FIT_XY"/>

1.3 加载Banner资源位实现代码如下

resourceView.requestResource(resourceId, new ResourceViewListener() {
    @Override
    public void onResourceLoadSuccess(@NonNull Resource resource) {
        // 拉取成功
    }

    @Override
    public void onResourceLoadFailed(@NonNull String s, @NonNull String s1) {
        // 拉取失败
    }

    /**
     *  帧位点击回调
     *  返回true代表该回调全部由宿主自行完成
     *  返回false则代表宿主不处理,SDK内部会通过webView来实现默认跳转
     */
    @Override
    public boolean onResourceClick(@NonNull String s) {
        return false;
    }
});


2 闪屏

说明:为避免闪屏网络请求对启动的阻塞,每次闪屏拉取都是 先取上一次成功的缓存渲染,再默默拉取最新资源位缓存到本地

2.1 参数说明

字段说明类型

imageContentMode

作用于图片类型资源位填充模式,默认值 FIT_CENTER
可选项:

  • CENTER
  • CENTER_CROP
  • CENTER_INSIDE
  • FIT_XY
  • FIT_START
  • FIT_CENTER
  • FIT_END
  • MATRIX

enum

2.2 在对应视图 xml 中添加 闪屏 控件

<com.bytedance.gmpreach.resource.splash.SplashResourceView
    android:id="@+id/splash_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:imageContentMode="FIT_XY"/>

2.3 加载闪屏实现代码如下

// resourceId 资源位 id
splashResourceView.requestResource(resourceId, new SplashResourceViewListener() {
    @Override
    public void onResourceShowSuccess(@NonNull Content content, @NonNull Resource resource) {
        //资源位曝光成功
    }

    @Override
    public void onResourceShowFailed(@NonNull String s, @NonNull String s1) {
        //资源位曝光失败
    }

    @Override
    public void onResourceShowFinished(@Nullable Resource resource) {
        //资源位展示结束,业务该自行处理下一步流程了
    }

    @Override
    public void onResourceLoadSuccess(@NonNull Resource resource) {
        //拉取成功
    }

    @Override
    public void onResourceLoadFailed(@NonNull String s, @NonNull String s1) {
        //拉取资源位失败
    }

    /**
     *  帧位点击回调
     *  返回true代表该回调全部由宿主自行完成
     *  返回false则代表宿主不处理,SDK内部会通过webView来实现默认跳转
     */
    @Override
    public boolean onResourceClick(@NonNull String s) {
        return false;
    }
});


四、自渲染方式接入资源位

1. 资源位数据模型说明

1.1 Resource

属性名类型含义
resourceIdstring资源位id
contentsList资源位下的帧位列表

1.2 Content

属性名类型含义
contentIdLong素材id
frameIdLong帧位id
resourceIdstring资源位id
sourceTypeContentType素材类型(Image图片 Text文本 content_collection自定义类型 Splash 闪屏类型)
textstring素材文本
imageUrlstring素材图片url
navigateUrlstring素材点击跳转链接url
customizeInfoStrstring自定义类型资源位内容合集
customizeInfoList自定义类型资源位内容合集
extrastring扩展json字段 用于存放和具体资源位类型关系比较大的信息 比如闪屏页存倒计时

1.3 CustomizeInfo

属性名类型含义
customizeTypeint自定义素材类型
textstring文本
imageUrlstring图片url
navigateUrlstring素材点击跳转链接url
fieldNamestring素材参数名称
fieldShowNamestring素材字段显示名称

2. 请求资源位数据

/**
  * 向服务端拉取资源位数据
  * @param ids 需要拉取的资源位列表
  * @param callBack 拉取成功或失败后的回调,成功则回调onSucceed,失败则回调onFailed
  */
GMPResourceSDK.INSTANCE.requestResourceData(Arrays.asList(resId), new CallBack() {
    /**
     * 回调在主线程
     * 请求成功的回调函数,resources即请求的资源位信息
     * 接入方需要根据返回的resources渲染UI
     * @param list 返回结果
     */
    @Override
    public void onSucceed(@NonNull List<Resource> list) {
    }

    /**
     * 回调在主线程
     * 请求失败的回调函数,errCode为错误码,errMsg为具体的错误信息
     * @param errCode 错误码
     * @param errMsg 错误信息
     */
    @Override
    public void onFailed(@NonNull String errCode, @NonNull String errMsg) {

    }
});


3. 自渲染接入闪屏页

说明

我们推荐您使用sdk渲染的方式接入闪屏页,但如果存在某些定制化接入的需求可以参考下列方法获取闪屏页配置信息并完成自渲染和数据上报

下列为Content类获取闪屏页配置的方法

方法名返回类型返回值含义
getCountDownInt获取素材配置的倒计时,单位为s,如果不存在则默认返回-1
getValidDateLong获取素材失效时间戳,单位为ms,如果不存在该字段则默认返回-1

使用示例:

int countDown = content.getCountDown();// 获取倒计时
long validDate = content.getValidDate();// 获取素材失效时间戳
if (validDate != -1 && validDate < System.currentTimeMillis()) {
  // 素材失效
  return;
}
//素材未失效
if (countDown != -1) {
    // 设置倒计时数据 
}


4. 自渲染埋点上报

埋点上报相关方法,请在对应的资源位帧位 首次展示成功、失败和点击时调用 GMPResourceSDK.INSTANCE.getResourceAction() 对应的类方法触发数据回传。

/**
 * 资源位展示成功时回调
 * @param content 素材数据类
 */
GMPResourceSDK.INSTANCE.getResourceAction().onResourceShowSuccess(content);

/**
 * 资源位展示失败时回调
 * @param content:展示的素材
 * @param errorMessage: 展示失败的原因
 */
GMPResourceSDK.INSTANCE.getResourceAction().onResourceShowFailed(content,errorMessage);

/**
 * 素材点击时回调
 * @param content:展示的素材
 * @param errorMessage:错误信息
 * @param isClickUrl:是否跳转链接
 */
GMPResourceSDK.INSTANCE.getResourceAction().onResourceClick(content,errorMessage,isClickUrl);

/**
 * 上报素材的展示停留时长
 * @param content:展示的素材
 * @param duration: 停留时长(单位是ms)
 */
GMPResourceSDK.INSTANCE.getResourceAction().onStayDuration(content,duration);
五、自渲染方式接入算法资源位

1. 简介

算法资源位是通过算法推荐结合用户的行为偏好数据,实现个性化的资源位物料下发

2. 算法资源位数据模型说明

  • RecParams(请求算法资源位的参数)
属性名类型含义
recResourceIdstring算法资源位id

spm

string

SPM(Super Position Model)全称超级位置模型,主要用于标识行为发生的位置。SPM位置编码由A/B/C/D四段构成,各分段分别代表 A:业务, B:页面, C:页面区块, D:区块内点位。段之间用$##$分隔,即A$##$B$##$C$##$D,spm各段建议传明文。某一段为空时直接传空字符串,如第二段为空, 则传“A$##$$##$C$##$D”。
1.业务:业务名称,如今日头条
2.页面:如首页、发现页-推荐等
3.页面区块:如广告位、猜你喜欢
4.区块内点位:在区块内的具体位置
预期上同一个位置下不同的资源位对应的spm是一致的

context_item_idstring算法资源位的推荐类型为相关推荐时,传入 RecContent 的 contentId
context_item_typestring算法资源位的推荐类型为相关推荐时,传入 RecContent 的 recContentType
pageint推荐列表页数(默认为0,轮播可以不传)
  • RecResource(请求算法资源位的返回response)
属性名类型含义
resourceIdstring资源位id
recContentsList素材列表
recParamsRecParams请求参数
recResourceTypeRecResourceType(枚举)算法资源位类型(BANNER:轮播 RECOMMENDED_LIST:推荐列表)
  • RecContent
属性名类型含义
resourceIdstring资源位id
contentIdstring素材id
frameIdstring帧位id
recContentTitlestring资源位素材标题,对应物料上传的item_title
recContentTypestring资源位素材类型,对应物料上传的item_type
recContentDataJSONObject资源位素材数据,对应物料上传的others里面的json内容
recResourceTypeRecResourceType(枚举)资源位资源位类型(BANNER:轮播 RECOMMENDED_LIST:推荐列表)

说明

算法资源位的物料是通过后端提供的openAPI同步插入的

3. 请求算法资源位

java:

  • 创建资源位参数
// 自定义字段,以map的形式传入,sdk会将其携带至请求与埋点中
HashMap<String, String> map = new HashMap<>();
map.put("customKey", "customValue");
RecParams recParams = new RecParams(
    recResourceId, 
    spm, 
    contextItemId, 
    contextItemType, 
    page,
    map);


  • 发起资源位请求
GMPResourceSDK.INSTANCE.requestRecResourceData(recParams, new RecCallBack() {
            @Override
            public void onSucceed(@NonNull RecResource recResource) {
                // 请求成功
            }

            @Override
            public void onFailed(@NonNull String errCode, @NonNull String errMsg) {
                 // 请求失败, 见六、异常错误码
            }
        });


  • 请求下一页的素材
// newPage 下一页数字
RecParams newRecParams = recParams.buildByPage(newPage);
GMPResourceSDK.INSTANCE.requestRecResourceData(newRecParams, new RecCallBack() {
            @Override
            public void onSucceed(@NonNull RecResource recResource) {
                // 请求成功
            }

            @Override
            public void onFailed(@NonNull String errCode, @NonNull String errMsg) {
                 // 请求失败, 见六、异常错误码
            }
});

4. 算法资源位埋点上报

/**
 * 资源位展示成功时回调
 * @param content 素材数据类
 */
GMPResourceSDK.INSTANCE.getResourceAction().onResourceShowSuccess(content);

/**
 * 资源位展示失败时回调
 * @param content:展示的素材
 * @param errorMessage: 展示失败的原因
 */
GMPResourceSDK.INSTANCE.getResourceAction().onResourceShowFailed(content,errorMessage);

/**
 * 素材点击时回调
 * @param content:展示的素材
 * @param errorMessage:错误信息
 * @param isClickUrl:是否跳转链接
 */
GMPResourceSDK.INSTANCE.getResourceAction().onResourceClick(content,errorMessage,isClickUrl);

/**
 * 上报素材的展示停留时长
 * @param content:展示的素材
 * @param duration: 停留时长(单位是ms)
 */
GMPResourceSDK.INSTANCE.getResourceAction().onStayDuration(content,duration);

完整资源位埋点参数说明可见资源位预置埋点说明

、异常错误码
错误码错误信息错误原因
400param empty参数错误,请检查 sdk 是否正常初始化,是否存在参数漏出传
500Server error服务器异常
100001network error设备网络异常
100002json serializa errorJson 序列化异常
100003resource id empty请求的资源位 id 为空
100004resource is empty资源位数据为空,请检查资源位配置和资源位 id 是否正确
100005render error资源位 sdk 渲染错误,不支持的渲染类型
100006authorization error鉴权失败
200001resource expire资源位过期资源位过期
200002resource download failed资源位素材下载失败
七、接入方问题排查 CheckList
  • FinderSDK 是否正确接入,在资源位初始化前是否完成 FinderSDK 的初始化,日志过滤"AppLog"可查看 FinderSDK 初始化相关日志。
  • 检查是否完成了资源位初始化的必选参数配置,日志过滤"Resource"查看相关日志。
  • 检查配置的域名是否正确,可抓包查看请求是否正常
八、常见问题

1. 如何判断是否初始化成功?

日志过滤"Resource"查看是否有资源位初始化完成日志

2. 发起资源位请求后无资源

检查初始化配置是否正确,可在日志中过滤"Resource"查看错误日志,或者抓包查看请求是否成功响应

3. SDK 缓存说明

  • 闪屏类型资源位:SDK 内部会一直缓存拉取成功的闪屏素材,展示前判断是否过期,过期则不展示
  • 其他类型资源位:SDK 内部会按照 网络请求返回数据>缓存数据>兜底数据的优先级返回资源位数据,其中缓存数据与兜底数据往往会在网络异常的情况下返回,因此推荐接入方使用带有图片缓存的图片加载库,可以确保兜底数据及缓存数据能生效,并且在极端情况下若这两类数据都无法正常返回会回调 onfail,这种情况下接入方可根据自己的业务逻辑添加容错数据
★版本记录

Android 弹窗、资源位SDK 版本记录