文档中心

功能接入

最近更新时间：2024.04.15 19:23:21

首次发布时间：2023.02.10 17:13:26

本文档将为您介绍 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 解码节省内存。

说明

若业务使用场景中有强需求 rgba 时，需谨慎使用该策略。

请在 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 将自动拼接完成静图的展示并播放视频。请通过以下内容完成加载配置。

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

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

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

说明

您可在客户端 APP 长按图片来播放视频。

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

模糊图占位

支持通过模糊图占位能力，使弱网情况下完整图未下载或未解码完成时，客户端能首先加载模糊占位图，以提升用户体验。当完整图加载完成并成功解码后，将替换模糊图并展示。veImageX 支持加载本地模糊图、加载网络模糊图和同时配置共三种方式。

加载本地模糊图的优先级大于加载网络模糊图。
加载本地模糊图的加载速度大于加载网络模糊图。
您需要自行管理本地模糊图的数据。

加载本地模糊图

加载网络下发模糊图

同时配置本地&网络下发模糊图

参考以下代码示例，传入指定的 BlurHash 码和完整图加载 URL。

说明

参考获取图片 BlurHash 码文档，了解如何获取指定图片的 BlurHash 码（模糊图）。
您还可以通过BlurHashConfig设置模糊图加载时的展示大小，取值越大解码越慢，最大值为 100。请根据业务需要，适当调整。

mSimpleDraweeView.setImageURI(Uri.parse("https://test.net/tos-cn-i-serviceid/demo.jpg"), "LEHV6nWB2yk8pyo0adR*.7kCMdnj", new BlurHashConfig(20, 20));

说明

使用前，请确保您已在完整图加载 URL 所使用的图片处理模板中开启了模糊图占位。
如果模板中配置了图像处理（缩放、水印）等或图像压缩，则将以图像处理&压缩后的结果图去生成 blurhash 码。

参考以下代码示例，传入待加载的完整图地址。在弱网情况下，客户端将根据图片请求 URL 中响应头携带的 BlurHash 字段，首先加载模糊图。

//开启加载网络模糊图
BlurHashMapUtils.setOpenBlurhash(true);
//具体模糊图加载配置
 ImageRequestBuilder builder = ImageRequestBuilder
                    .newBuilderWithSource(Uri.parse("https://test.net/tos-cn-i-serviceid/demo.jpg~tplv-ut**ti-blurhash.jpg"))//待加载的完整图 URL，图片处理模板中需开启模糊图占位配置
                    .setBlurHashOptions(new BlurHashConfig(20,20)); //模糊图加载尺寸，单位为 px，取值越大解码越慢，最大值为 100。请根据业务需要，适当调整。
 DraweeController controller = Fresco.newDraweeControllerBuilder()
										.setEnableHeaderBlurhash(true)
                    .setImageRequest(builder.build())
                    .setOldController(simpleDraweeView.getController())
                    .build();
simpleDraweeView.setController(controller);

您可以同时设置两种模糊图加载配置。同时指定时，本地模糊图优先级最高会优先被加载。支持以下两种方式，具体代码如下所示：

方式一：

draweeViewImg3.setImageURI(Uri.parse("https://test.net/tos-cn-i-serviceid/demo.jpg~tplv-ut**ti-blurhash.jpg"), "LEHV6nWB2yk8pyo0adR*.7kCMdnj", new BlurHashConfig(20, 20));

方式二：

//开启加载网络模糊图
BlurHashMapUtils.setOpenBlurhash(true);
//具体模糊图加载配置
ImageRequestBuilder builder = ImageRequestBuilder
        .newBuilderWithSource(Uri.parse("https://test.net/tos-cn-i-serviceid/demo.jpg~tplv-ut**ti-blurhash.jpg")) //待加载的完整图 URL，图片处理模板中需开启模糊图占位配置
        .setBlurHashOptions(new BlurHashConfig(20,20));//模糊图加载尺寸，单位为 px，取值越大解码越慢，最大值为 100。请根据业务需要，适当调整。
DraweeController controller = Fresco.newDraweeControllerBuilder()
				.setEnableHeaderBlurhash(true)
        .setImageRequest(builder.build())
        .setOldController(simpleDraweeView.getController())
        .build();
simpleDraweeView.setController(controller, "LEHV6nWB2yk8pyo0adR*.7kCMdnj", new BlurHashConfig(20, 20));

初始化 TTNet（可选）

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

说明

您可以通过 veImageX 控制台中 SDK 配置下发开启 TTNet 网络库的 HTTP2 和预连接等能力，具体请参考客户端配置下发。

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 名称，根据实际业务填写

com.bytedance.fresco.cloudcontrol.InitConfig initConfig = com.bytedance.fresco.cloudcontrol.InitConfig(
    context,
    aid,
    appName,
    channel,
    versionName,
    versionCode,
    deviceId,
    InitConfig.CHINA,   //国内版本设置为 CHINA；新加坡地区设置为 SINGAPORE；
    "M2ZmYzkzZjUtN2", // Token,，如实填写，您可在 接入准备-购买授权 获取Token
    aencodedAuthCode   // 授权码List<String>，如实填写，您可在 接入准备-购买授权 获取授权码
);

日志上报

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

说明

性能日志上报默认开启，您无需手动修改参数。
该能力依赖 Applog 模块，若未完成初始化和启动 Applog，则无法使用该功能。

开启大图监控日志上报

开启感知日志上报

开启大图监控日志上报和自定义命中大图条件，命中大图条件如下所示：

图片文件大小超过阈值，默认值为 20 MB。
图片分辨率大小大于展示 view 尺寸的自定义倍数阈值，默认值为 2 倍。
图片内存大小超过自定义阈值，默认值为屏幕尺寸内存大小。

说明

若某张图片命中了多个条件，则将在多个命中维度下上报该条图片数据，具体请前往感知指标监控-大图监控查看日志上报数据。

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())

开启后请进入 veImageX 控制台 > 服务质量监控 > 感知指标监控界面下的采集样本量、内存命中率、磁盘命中率查看感知监控日志上报数据。

自定义上报标示

您可根据实际业务，在客户端代码添加自定义业务标识（bizTag）和场景标识（sceneTag）。通过自定义标识，对特定业务或某一类图片进行区分和标记。您可在质量监控筛选并查看该维度下客户端上报情况，以便更好地了解和分析不同业务和场景下的图片加载情况。

业务标示：用于标识下发图片的服务器。例如，服务器下发图片时，URI 中会携带业务标示。
场景标示：用于标识图片在客户端的展示场景。例如在哪个 Activity、Fragment 展示，如 xxxActivity_xxxFragment。

请参考以下步骤，添加自定义标识。

定义一个 CallerContext 类，此处以 XXACallerContext 为例。该类可以包含 bizTag 和 sceneTag 两个属性，用于设置业务标识和场景标识。

说明

您可定义多个 CallerContext，或者通过 CallerContext 中的属性设置来区分不同的业务场景。

public class XXACallerContext {
    private String bizTag;
    private String sceneTag;

    public XXACallerContext(String bizTag, String sceneTag) {
        this.bizTag = bizTag;
        this.sceneTag = sceneTag;
    }

    public String getBizTag() {
        return bizTag;
    }

    public void setBizTag(String bizTag) {
        this.bizTag = bizTag;
    }

    public String getSceneTag() {
        return sceneTag;
    }

    public void setSceneTag(String sceneTag) {
        this.sceneTag = sceneTag;
    }
}

指定加载的图片 URL，同时根据业务场景自定义该场景的业务标识和场景标识。

ImageRequestBuilder builder = ImageRequestBuilder
        .newBuilderWithSource(Uri.parse("https://example.com/image.jpg")); //指定图片 URL

DraweeController controller = Fresco.newDraweeControllerBuilder()
        .setOldController(mSimpleDraweeView.getController())
        .setAutoPlayAnimations(true) // 指定自动播放动图
        .setImageRequest(builder.build())
        .setCallerContext(new XXACallerContext("bizTagA","sceneTagA")) // 根据业务场景，指定自定义标识
        .build();

图片加载完成后，根据CallerContext 来区分业务场景，并上报通过网络下载的图片的业务标识、场景标识监控信息。

FrescoMonitor.setMonitorHook(new IMonitorHook() {
  @Override
  public Pair<Boolean, Map<String, Object>> onMonitorCompleted(@Nullable ImageRequest request,
      @Nullable Object callerContext, String requestId, @Nullable JSONObject monitorData, boolean isSuccess) {
    Map<String, Object> hashMap = new HashMap<>();
    //通过 callerContext 以及 callerContext 内部的字段值 来区分业务场景
    if(callerContext instanceof XXACallerContext){
        hashMap.put("biz_tag", callerContext.getBizTag()); //业务标识，接入方自定义数据
        hashMap.put("scene_tag", callerContext.getSceneTag()); //场景标识，接入方自定义数据
    }
    
   if (monitorData != null) {
      // 过滤图片，判断图片是否通过网络下载，仅上报通过网络下载的图片标识
      try {
        isNetwork = (boolean) monitorData.get(FrescoMonitorConst.IS_NETWORK_DOWNLOAD);
      } catch (JSONException e) {
        e.printStackTrace();
      }
      return new Pair<>(isNetwork, hashMap);
    }
    return null;
  }
});

埋点日志上报回调

说明

该能力依赖 Applog 模块，若未完成初始化和启动 Applog，则无法使用该功能。

在 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 用于加密文件的加密密钥，用于解密加密数据。

方式一：简单加载

方式二：自定义加载

参考以下代码示例依次填入图片加载 URL、公钥、对称密钥。

draweeViewImg.setImageURI(url, pubKey, urlKey);

参考以下代码示例依次填入图片加载 URL、公钥、对称密钥，此外支持您自定义 ImageRequest 的各种属性，如缩放、剪裁等。

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);

云控配置下发

说明

云控中自定义日志上报采样率配置依赖 Applog 模块，若未完成初始化和启动 Applog，则该配置无法生效。

在 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" ]
}