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

功能接入

最近更新时间2024.02.05 16:45:22

首次发布时间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);
	

heic 静图渐进式

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

全局开启静图渐进式加载,代码示例如下所示:
ImagePipelineConfig.getDefaultImageRequestConfig().isProgressiveRenderingHeicEnabled  = true
	

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"/>
  1. 支持单独设置图片 URL 和视频 URL 或同时设置,代码示例如下所示:

说明

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

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

初始化 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 已支持开启大图监控日志和感知日志上报能力,您可在控制台查看相关指标。代码示例如下所示:

说明

性能日志上报默认开启,您无需手动修改参数。

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

  1. 图片文件大小超过阈值,默认值为 20 MB。

  2. 图片分辨率大小大于展示 view 尺寸的自定义倍数阈值,默认值为 2 倍。

  3. 图片内存大小超过自定义阈值,默认值为屏幕尺寸内存大小。

说明

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

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

埋点日志上报回调

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

云控配置下发

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