You need to enable JavaScript to run this app.
导航
veImageX
  • 文档首页
    • /
  • veImageX

iOS 接入文档（旧版）

最近更新时间：2022.10.17 20:18:25

首次发布时间：2021.02.23 10:42:27

我的收藏

一、阅读对象

  1. 本文档部分内容为 veImageX 专属能力，使用前请开通veImageX相关服务，未注册用户可注册账号免费试用。

  2. 本文档为技术文档，建议阅读者具有基本的 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 等不同渠道标识，便于统计区分。
appNameApp 名称，用于统计使用。

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
    }];