功能接入

本文档将为您介绍 Android 加载 SDK 的能力接入说明。

Android 9.0 libwebp 解码

在 Android 9.0 版本，系统原生的 Webp 解码方式存在部分问题，推荐您在 Android 9.0 版本使用 libwebp 解码方式。

ImagePipelineConfig.Builder builder = ImagePipelineConfig.newBuilder(this);
// 对 9.0 版本打开 libwebp 解码
builder.experiment().setPieDecoderEnabled(true);

在 honor magic2 测试机上对同一图片进行 benchmark 测试，Android 原生解码时间为 15.9 ms，libwebp 解码时间为 16.4 ms，无明显性能差异。

低内存策略

该策略主要是通过使用默认解码器解码 bitmap 时对未指定 bitmapConfig 以及无透明通道的图片使用 565 解码节省内存。

请在 BDFresco 初始化前配置以下代码：

ImageDecodeBitmapConfigStrategy.setStrategy(ImageDecodeBitmapConfigStrategy.MEMORY_AT_LEAST);

OOM 兜底策略

开启后可获取图片库 OOM 异常，并降低应用 OOM 崩溃率，但已经发生 OOM 异常的图片会无法加载。

ImagePipelineConfig.Builder builder = ImagePipelineConfig.newBuilder(this)
builder.experiment().setOomOptEnabled(true); //开启

awebp 动图渐进式加载

BDFresco 支持 awebp 格式的动图渐进式加载，可实现类似视频的边下边播效果（但无法拖动进度），同时降低动图首帧展示耗时，帮助提升加载体验。

ImagePipelineConfig.getDefaultImageRequestConfig().setProgressiveRenderingAnimatedEnabled(true);
	

ImageRequestBuilder builder = ImageRequestBuilder
        .newBuilderWithSource(uri)
        .setProgressiveRenderingAnimatedEnabled(true);
DraweeController controller = Fresco.newDraweeControllerBuilder()
        .setAutoPlayAnimations(true)
        .setImageRequest(builder.build())
        .setOldController(getController())
        .build();
setController(controller);
	

heic 静图渐进式

heic 静图渐进式加载（heic 缩略图加载），是指通过渐进加载方式来优化 heic 静图加载的体验，主要收益来自于可感知耗时的优化，即通过先看到图片整体轮廓的模糊效果，直到图片完全加载出来。

ImagePipelineConfig.getDefaultImageRequestConfig().isProgressiveRenderingHeicEnabled  = true
	

mSimpleDraweeView = findViewById(R.id.my_image_view);
ImageRequestBuilder builder = ImageRequestBuilder.newBuilderWithSource(Uri.parse("url"));
builder.setProgressiveRenderingHeicEnabled(true);
DraweeController controller = Fresco.newDraweeControllerBuilder()
        .setOldController(mSimpleDraweeView.getController())
        .setAutoPlayAnimations(true)
        .setImageRequest(builder.build())
        .build();
mSimpleDraweeView.setController(controller);
	

HEIF 格式加载

支持 HEIF 格式图片加载，请在ImagePipelineConfig.Builder中进行设置。代码示例如下所示：

final  PoolFactory  factory = new PoolFactory(PoolConfig.newBuilder().build());
ImagePipelineConfig.Builder builder = ImagePipelineConfig.newBuilder(this)
 .setPoolFactory(factory)      
         .setImageDecoderConfig(ImageDecoderConfig.newBuilder().addDecodingCapability(
                HeifDecoder.HEIF_FORMAT,
                new HeifDecoder.HeifFormatChecker(),
                new HeifDecoder.HeifFormatDecoder(false))//true优先使用系统解码，false优先使用软解；软硬解会相互兜底
                .build());
Fresco.initialize(this, builder.build());

转码

仅支持动图格式（awebp、heif）转 gif 格式，当 Uri 是静态图或 Gif 格式时，系统会直接复制至目标文件。代码示例如下所示：

Executors.newSingleThreadExecutor().submit(new Runnable() {
    @Override
    public void run() {
        AnimatedTranscoder.animatedToGif(TestImageActivity.this, Uri.parse("http://s6.pstatp.com/site/download/app/apk/news_release2/img/android_push_permission_guid_img_night4.heif"),
                new File(TestImageActivity.this.getApplicationContext().getCacheDir() +
                        "/" + System.currentTimeMillis()), new AnimatedTranscoder.Callback() {
                    @Override
                    public void onSuccess() {
                        Log.d("tag", "onSuccess");
                    }

                    @Override
                    public void onError(int errorCode, Throwable t) {
                        if (errorCode == AnimatedTranscoder.ERROR_DOWNLOAD) {
                            Log.d("tag", "download error");
                        } else if (errorCode == AnimatedTranscoder.ERROR_SAVE_FILE) {
                            Log.d("tag", "save file error");
                        } else {
                            Log.d("tag", "trans code error");
                        }
                    }

                });
    }
});

Live Photo 加载

veImageX 已支持对 Live Photo 图像进行加载，由于 Live Photo 本质上是由静图与视频的组合，所以您需要分别提供静图和视频的 URL，SDK 将自动拼接完成静图的展示并播放视频。请通过以下内容完成加载配置。

1. 集成 LivePView 组件，并自定义图像展示 view 的宽高（单位为 dp），图像资源被加载时将自适应缩放适配 view 范围，代码示例如下所示：

<com.bytedance.livephoto.LivePView
    android:layout_width="150dp"
    android:layout_height="150dp"/>

2. 支持单独设置图片 URL 和视频 URL 或同时设置，代码示例如下所示：

/* 单独设置图片 url */
public void setImageURI(String url)
/* 单独设置视频 url */
public void setVideoURI(String url)
/* 同时设置图片和视频 url */
public void setBothUrl(String imgUrl, String videoUrl)

初始化 TTNet（可选）

TTNet 是经过高度优化的自研客户端网络库，性能更加稳定。如果您需要接入网络库 TTNet，请首先完成网络库 TTNet 初始化。具体代码如下所示：

String aid = "xxx";                // App ID，应用管理获取
String deviceId = "xxx";           // 设备 ID，根据实际业务填写
String versionName = "0.0.1";      // App 版本号，根据实际业务填写
String versionCode = "1";          // App 版本 code，根据实际业务填写
String channel = "xxx";          // 渠道，根据实际业务填写
String appName = "xxx";         // App 名称，业务方 App 名称，根据实际业务填写
String token = null;               // token，无需获取，传入 null 即可
List<String> authCode = null;      // authCode，无需获取，传入 null 即可
com.bytedance.fresco.cloudcontrol.InitConfig initConfig = com.bytedance.fresco.cloudcontrol.InitConfig(
    context,
    aid,
    appName,
    channel,
    versionName,
    versionCode,
    deviceId,
    InitConfig.CHINA,   //国内版本设置为 CHINA；美东地区设置为 US_EAST；新加坡地区设置为 SINGAPORE；
    token,
    authCode
);

日志上报

SDK 已支持开启大图监控日志和感知日志上报能力，您可在控制台查看相关指标。代码示例如下所示：

FrescoMonitor.setExceedTheLimitBitmapMonitorEnabled(true); //开启大图监控日志上报
FrescoMonitor.setExceedTheLimitBitmapMonitorLimit( limitFileSize,  limitBitmapContrast,  limitRamSize); //limitFileSize：文件大小阈值；limitBitmapContrast：bitmap和view尺寸倍数阈值；limitRamSize：内存大小阈值
   

val draweeConfigBuilder = DraweeConfig.newBuilder().addGlobalControllerListener(FrescoControllerListener())
Fresco.initialize(context, builder.build(), draweeConfigBuilder.build())
   

埋点日志上报回调

在 2.1.0-tob 及之后 SDK 版本已支持埋点日志上报回调，该能力支持通过监听回调的方式获取图片日志，可用于搭建符合业务特性的数据指标体系，进行个性化数据分析。代码示例如下所示：

FrescoMonitor.addImageTraceListener(this, object : ImageTraceListener {
    override fun onImageLoaded(isSucceed: Boolean, requestId: String?, jsonObject: JSONObject?) { //通过jsonObject参数是否含有IS_NETWORK_DOWNLOAD字段来判断图片请求是否经过网络
        //仅上报经过网络请求的图片加载结果，如果从缓存中拿到图片也想上报信息，则FrescoMonitor.setReportHitCacheEnabled(true)
        // MonitorUtils.monitorCommonLog(FrescoMonitorConst.MONITOR_IMAGE_V2, jsonObject);
        FLog.d(TAG_MONITOR, "onImageLoaded : $jsonObject")
        //接入方获取到json后可自行处理
    }
}

加载加密图片

在 2.4.2-tob 及之后 SDK 版本已支持对加密图片进行解密后转码并展示，支持以下两种方式进行加载，您可根据实际需求选择使用。解密所需参数如下：

• 加密图片访问地址：图片 URL。

• 公钥：您在 veImageX 控制台获取的数据加密密钥，用于解密对称密钥。

• 对称密钥：您在上传 SDK 用于加密文件的加密密钥，用于解密加密数据。

draweeViewImg.setImageURI(url, pubKey, urlKey); 
   

ImageRequestBuilder builder = ImageRequestBuilder
        .newBuilderWithSource(Uri.parse(url))
        .setPublicKey(pubKey)
        .setUrlKey(urlKey);
DraweeController controller = Fresco.newDraweeControllerBuilder()
        .setImageRequest(builder.build())
        .setOldController(draweeViewImg.getController())
        .build();
draweeViewImg.setController(controller);
   

云控配置下发

在 2.2.0-tob 及之后 SDK 版本已支持云控配置下发，该能力支持在控制台动态下发客户端 SDK 配置参数，实现策略最优的目的。SDK 会在初始化时拉取云控配置参数，具体请参考客户端配置下发。

设置隐私数据采集开关

设置 Android ID 采集开关

关闭 Android ID 会影响 did 卸载重装一致性，请谨慎关闭。设备的 Android ID 采集默认开启，如需关闭：

config.setAndroidIdEnabled(false);

如需移除Android ID采集代码，可以在全埋点 Plugin 中配置：

// 本功能仅支持 2.2.0-tob 及以上版本
teaExtension {
    // ... 其他配置
    trackBlackList = [ "ANDROIDID" ]
}

设置 MEID 采集开关

设备的imei地址采集默认开启。如需关闭：

config.setImeiEnable(false);

如需移除 IMEI 和 MEID 采集的相关代码，可以在全埋点 Plugin 中配置：

// 本功能仅支持 2.2.0-tob 及以上版本
teaExtension {
    // ... 其他配置
    trackBlackList = ["IMEI_MEID"]
}

设置 MAC 地址采集开关

设备的 mac 地址采集默认开启。如需关闭：

config.setMacEnable(false);

如需移除 MAC 地址采集的相关代码，可以在全埋点插件 Plugin 中配置：

// 本功能仅支持2.2.0-tob及以上版本
teaExtension {
    // ... 其他配置
    trackBlackList = ["MAC_ADDRESS"]
}

设置 OAID 采集开关

设备的 OAID 信息采集默认开启。如需关闭：

config.setOaidEnabled(false);

如需移除 OAID 采集的相关代码，可以在全埋点 Plugin 中配置：

// 本功能仅支持2.2.0-tob及以上版本
teaExtension {
    // ... 其他配置
    trackBlackList = [ "OAID" ]
}