iOS 接入文档（旧版）--veImageX-火山引擎

文档中心

立即注册

导航

iOS 接入文档（旧版）

最近更新时间：2022.10.17 20:18:25首次发布时间：2021.02.23 10:42:27

一、阅读对象

本文档部分内容为 veImageX 专属能力，使用前请开通veImageX相关服务，未注册用户可注册账号免费试用。
本文档为技术文档，建议阅读者具有基本的 iOS 开发能力。

二、支持系统

系统要求版本为 iOS 9.0 及以上。

三、开发环境

推荐开发者使用 Xcode11 以上作为自己的开发工具，本开发文档也是基于 Xcode 开发环境下进行编写的。

四、集成方式

CocoPods 集成
在您工程的 Podfile 中添加依赖，并执行 pod install 即可。Podfile 内容追加如下部分：

source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/bytedance/cocoapods_sdk_source_repo.git'
source 'https://github.com/volcengine/volcengine-specs.git'

pod 'TTSDK', 'x.x.x.x-standard', :subspecs => [
  'Image',   // 图片，其中x.x.x.x代表版本号，推荐使用最新稳定版，具体版本号可以从这获取：https://github.com/volcengine/volcengine-specs/tree/master/TTSDK
]

五、接入说明

Swift支持

需要使用 Modular Header

监控上报初始化

相关参数说明如下所示。

参数	说明
AppID（appID）	SDK 用于打点监控上报的最小单元。通过此将数据进行隔离上报，同时通过 AppID 可以拉取对应的云控配置，比如客户端采样率、网络优化参数等。
channel	渠道标识，用于区分统计不同渠道来源的图片服务质量数据。比如可传入huawei、oppo 等不同渠道标识，便于统计区分。
appName	App 名称，用于统计使用。
serviceVendor	服务所在地区。主要根据 App 是否发布在海外使用决定上报的日志的物理位置，默认国内，海外版本需要额外设置。为满足 GDPR 合规性要求，请如实填写。说明如果 App 为非中国区域用户服务，则需修改设置为海外，采样后的日志则自动上报到海外地区。

// 监控模块初始化，AppID、渠道、appName、服务所在地区，默认国内，海外版本需要额外设置（serviceVendor）
BDAutoTrackConfig *config = [BDAutoTrackConfig configWithAppID:appID launchOptions:nil];
    config.channel = @"local_test";
    config.appName = @"dp_tob_sdk_test2";
    config.showDebugLog =  **NO** ;
    config.serviceVendor = BDAutoTrackServiceVendorCN;
    config.logger = ^(NSString *  **_Nullable**   log) {
        NSLog(@"applog -- %@", log);
    };
    config.logNeedEncrypt =  YES ;
    config.appID = appID;
    [BDAutoTrack startTrackWithConfig:config];
      

    // 配置图片库 AppID、是否是海外产品：BDImageServiceVendorCN、BDImageServiceVendorVA,
BDImageServiceVendorSG
     
// token 用于获取增值库授权码，authCodes 为本地设置授权码
    BDWebImageStartUpConfig * imageConfig = [BDWebImageStartUpConfig new];
    imageConfig.appID = appID;
    imageConfig.serviceVendor = BDImageServiceVendorCN;
    imageConfig.token = @"N2IwYmI1M2YtMTJlZS00NTUwLTk3NjgtNmFlYzk4NzgxOTU1";
    imageConfig.authCodes = @[ @"eyJBZGRPbiI6ImFkZC1vbi0xIiwiUGFja2FnZU5hbWUiOiJ0ZXN0LnBhY2thZ2UuYW5kcm9pZCIsIkJ1bmRsZUlEIjoidGVzdC5idW5kbGUuaW9zIiwiU3RhcnRUaW1lIjoxNjAzMjcxNzA1LCJFbmRUaW1lIjoxNjA1OTUwMTA1LCJTdWl0ZUlEIjoiMDAwMSIsIlZlcnNpb24iOiJ2MSIsIlNpZ25hdHVyZSI6InFtbkppL0ptM3JTREtlb0NLWi9zNW82aXFrU1dhZkRWa2gxVEJpcjY3eHNXbWRZMG8rUUxFVC9sM1MvdjRZM2w1UkFkRS9GV1EyZnAzTEdrRk5EWGVuM3UvZk9aVGw5bWN0WmJ4TFgxc01HZjl6OEUxcW0wcm8wUzB5dGZLNUVkNXBRZXF5WldlLzNsMVQ1aC9zajIyTDNSVzh2b0dDdW9pODdaOS8zWFRNcjVybVc3bjVSbGN1R0R2VWVKZ0Y3ZkV6bFZ5VVVRS0tXa3dlNUgyUHJaRmZBMDdoWVlKbDRITzdNa3VrbTgxcTE4enJaZnhDclViS2lzc01VdSszTi9kWmNWcjN2VjZzK2xpdktYRzZhNDJSNVluUURHQmZ1NXl1WnVFRmRiVlNvcnB5dnhsdWg3QnZGY1JnQ1krOVhjcVNneU43OFBERUk5cXVsbFFUbjZBUT09In0="];
    [[BDWebImageManager sharedManager] startUpWithConfig:imageConfig];

基础能力接入说明

1. BDWebImageURLFilter

BDWebImageManager 支持设置 URLFilter
\- (NSString \*)identifierWithURL:(NSURL \*)url;
实现此方法后 manager 内部调度会根据具体的 URL-key 计算策略来唯一标识一个图片请求，例如：

多 CDN域名映射为同一个图片，内部缓存和下载策略去重。
图片后缀兼容，例如多处访问同一个图片但是使用不同格式 webp 图片下载之后可以不用下载 jpg 版本。
多图片 size 支持。

2. BDWebImageRequest

每个图片请求会对应一个 BDWebImageRequest，manager 会内部调度决定取缓存策略或者下载策略，多个相同 request 内部只会下载一次。
request 支持设置超时时间，重试备选 URL，重试次数，缓存策略等。

3. 备选 URL 机制

@property (nonatomic, strong) NSArray<NSURL *> *alternativeURLs;

设置 alternativeURLs 后如果默认 URL 请求失败会判断失败原因，如果由于设备网络原因则终止请求返回错误，如果遇到超时、DNS 解析失败、链接主机失败等原因会触发备选 URL 逻辑，默认按照数组顺序重试，直到所有 URL 失败才会返回错误。

4. 重试次数

@property (nonatomic, assign)NSInteger maxRetryCount;

如果最大重试数大于 1，下载失败后会判断失败原因，如果由于设备网络原因则终止请求返回错误，如果遇到超时、DNS 解析失败、链接主机失败等原因会触发重试逻辑，超过重试次数后返回结果。
如果备选 URL和重试逻辑重试存在，先触发备选 URL 逻辑。
在下载时指定 BDImageNoRetry Option，下载失败都不会重试。

5. 从 URL 加载图片

//从网络加载图片
//完整图片加载
//如果命中内存图片默认不会提供data，需要提供data请加上BDImageRequestNeedCachePath
- (BDWebImageRequest *)bd_setImageWithURL:(NSURL *)imageURL
                          alternativeURLs:(NSArray *)alternativeURLs
                              placeholder:(UIImage *)placeholder
                                  options:(BDImageRequestOptions)options
                          timeoutInterval:(CFTimeInterval)timeoutInterval
                                cacheName:(NSString *)cacheName
                              transformer:(BDBaseTransformer *)transformer
                                 progress:(BDImageRequestProgressBlock)progress
                               completion:(BDImageRequestCompletedBlock)completion;
//提供一组便捷方法，可以根据需求选择
NSURL *url = [NSURL URLWithString:@"https://i.v2ex.co/8yc8q36x.jpeg"];
[imageView bd_setImageWithURL:url];

6. 加载动图

支持动图播放需要显示控件支持。只需要把 UIImageView 替换为 BDImageView 即可。
BDImageView 背后由 BDAnimatedImagePlayer 支持动图调度，支持边下边播，边解边播，自动处理内存缓存策略，默认播放策略按照图片 meta 信息，可以设置循环次数，缓存策略详细信息参照注释说明。

UIImageView *imageView = [BDImageView new];
[imageView bd_setImageWithURL:[NSURL URLWithString:@"https://img.wowoqq.com/allimg/180112/1-1P112042I9-50.gif"]];

7. 渐进式图片加载

//边下载边显示
NSURL *url = [NSURL URLWithString:@"https://i.v2ex.co/8yc8q36x.jpeg"];
[imageView bd_setImageWithURL:url options:BDImageProgressiveDownload];
//对于动图，类似 chrome 浏览器播放动图的效果，会一边下载一边播放已经下载好的帧
[imageView bd_setImageWithURL:[NSURL URLWithString:@"https://ws4.sinaimg.cn/large/006tKfTcly1fnl3r44e79g30am062qv8.gif"] options:BDImageProgressiveDownload];

8. 加载，处理图片

//BDWebImage 已经预置了一些常用 transformer，比如加圆角
BDRoundCornerTransformer *transformer = [BDRoundCornerTransformer defaultTransformer];
    [imageView bd_setImageWithURL:url placeholder:nil options:BDImageProgressiveDownload transformer:transformer progress:^(BDWebImageRequest *request, NSInteger receivedSize, NSInteger expectedSize) {
        progress = (float)receivedSize / expectedSize;
} completion:^(BDWebImageRequest *request, UIImage *image, NSData *data, NSError *error, BDWebImageResultFrom from) {
 if (from == BDWebImageResultFromDiskCache) {
            NSLog(@"load from disk cache");
        }
    }];

9. 图片缓存

由于业务场景不同，强烈建议业务方设置自己的缓存策略，否则使用默认缓存策略可能性能表现可能有较大差异。

BDImageCacheConfig *cacheConfig = [[BDImageCacheConfig alloc] init];
    cacheConfig.clearMemoryOnMemoryWarning = YES; //收到 memory warning 的时候清空内存缓存
    cacheConfig.clearMemoryWhenEnteringBackground = YES; //应用进入后台清空内存缓存
    cacheConfig.memoryCountLimit = NSUIntegerMax;    //内存缓存数量限制，默认无限制
    cacheConfig.memorySizeLimit = NSUIntegerMax; //内存缓存大小限制，默认无限制。单位 byte
    cacheConfig.memoryAgeLimit = 12 * 60 * 60; //内存缓存存活时长 12 小时
    cacheConfig.trimDiskWhenEnteringBackground = YES;//应用进入后台时清理超限或过期的磁盘缓存
    cacheConfig.diskCountLimit = NSUIntegerMax;    //磁盘缓存对象个数
    cacheConfig.diskSizeLimit = 256 * 1024 * 1024; //磁盘缓存大小限制 256M
    cacheConfig.diskAgeLimit = 7 * 24 * 60 * 60; //磁盘缓存最大时长 7 天
    [BDImageCache sharedImageCache].config = cacheConfig;
    BDImageCache *cache = [BDImageCache sharedImageCache];
    cache.totalDiskSize;//同步获取磁盘缓存的所有数据的字节数
    [cache trimDiskCache];//同步根据设置的最大磁盘大小，对象数量和过期时间，清除过期的缓存
    [cache clearMemory];//清除内存缓存中的所有数据
    [cache clearDiskWithBlock:^{
        NSLog(@"disk cleared");//主线程
    }];

10. 图片预加载

NSURL *url = [NSURL URLWithString:@"http://p3.pstatp.com/large/w960/4775000261266dd5c0eb.heic"];
[[BDWebImageManager sharedManager] prefetchImageWithURL:url category:nil  options:BDImageRequestDefaultOptions];

进阶能力接入说明

1. URL 映射

指向同一个文件的不同 url 共用一份缓存，典型场景如多个CDN域名。业务方可以继承 BDWebImageURLFilter 类, 重写方法 - (NSString *)identifierWithURL:(NSURL *)url; 实现自己的 hash 让同一张图片的不同 url hash 结果相等。

2. 跳过解码过程

只需要下载图片到本地磁盘然后告诉调用方磁盘路径，典型场景如头条文章详情页 webview。调用时增加 BDImageRequestIgnoreImage 和 BDImageRequestNeedCachePath 选项，可以跳过解码过程，节省性能。

3. 缓存控制

控制图片缓存大小，通过自定义 BDImageCacheConfig 中各项，平衡内存占用和 CPU 占用。

4. 预解码

发送请求时，可以使用 BDImageNotDecoderForDisplay 指定是否 Force Redraw 解码；也可以使用 isDecoderForDisplay 来统一开关。默认是会 Force Redraw ，这可以提高 FPS，但对于大图会出现内存峰值。

5. 自动缩小

下载图片时，可以使用 BDImageScaleDownLargeImages 来自动缩小，如果图片生成的 CGImage 大于 60M，则会把图片的长宽等比例缩小，缩小到 CGImage 为 60M。生效的前提是没有关闭 Force Redraw。如果发生缩小操作，下载回调中的 image 为缩小后图片，而 data 为原始数据。可以通过 UIImage 的 bd_isDidScaleDown 属性判断是否发生了缩小。

6. 设置下载器默认Headers

有时会为 http/https 请求增加一些自定义的 headers，可以使用下面的方式设置：

[BDWebImageManager sharedManager].downloadManagerDefaultHeaders = @{@"custom-key": @"custom-val"};

7. 设置下载默认超时

服务器响应，默认为 30s。

服务器响应的默认超时时间
    */
    [BDWebImageManager sharedManager].timeoutInterval = 10;

资源下载超时，默认为 30s。

/**
     资源下载的默认超时时间
     */
    [BDWebImageManager sharedManager].timeoutIntervalForResource = 100

8. 支持原生播放动图

BDImage 在动图播放做了许多优化，这些优化需要与 BDImageView 一起使用才能生效。如果需要在原生的 UIImageView、UIButton 上播放动图，需要通过下面方法适配一下系统接口。

// 加载本地的动图
    UIImageView *imageView = [UIImageView new];
    BDImage *image = [BDImage imageWithContentsOfFile:path];
    [image preloadAllFrames];
    imageView.image = image;
      

    // 加载网络的动图
    // imageview/button bd_setImageWithURL方法与原来接口不变, 不需要额外设置
    [imageView bd_setImageWithURL:[NSURL URLWithString:url]];
      

    // BDWebImageManager requestImage 等方法，需要指定生成支持原生播放的动图
    [[BDWebImageManager sharedManager] requestImage:[NSURL URLWithString:url] options:BDImageRequestPreloadAllFrames complete:^(BDWebImageRequest *request, UIImage *image, NSData *data, NSError *error, BDWebImageResultFrom from) {
     // do something
    }];