6.1 概述
PLVVodUploadSDK 是易方信息科技股份有限公司提供的可集成于项目中用于 iOS 设备上传视频文件到服务器的 SDK，支持断点续传。使用本 SDK 需要在保利威视频云平台注册账号，并使用该账号进行登录，上传后的视频文件可在该视频平台上进行查看、剪辑、播放、删除等操作。
6.2 文件目录
PLVVodUploadSDK 的文件目录如下，其中红色虚线方框里的是 SDK 的 public 文件：：
6.3 开始集成
上传 SDK 支持 iOS 8.0 以上 iOS 设备，需具备 Xcode 10.0 以上开发环境、CocoaPods 1.5.3 以上。关于如何安装 CocoaPods，文档 "2.快速集成" 的 2.2 有讲。
在 Podfile 文件中新增以下内容：
pod 'PLVVodUploadSDK'
然后，使用终端工具切换到项目所在路径下，执行如下命令：
6.4 SDK 登录
PLVUploadClient 是进行登录、上传请求的操作类，使用 PLVUploadClient 的方法 -loginWithUserId:secretKey: 进行登录，方法声明如下（参数 userId、secretKey 可登录保利威视频云平台获取）：
/**
SDK 登录
@param userId 用户 ID
@param secretKey 用户 secretKey
*/
- (void)loginWithUserId:(NSString *)userId secretKey:(NSString *)secretKey;
以在 AppDelegate 中进行 SDK 登录为例，示例代码如下：
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
NSString *userId, secretKey; // 初始化为用户自己的 userId、secretKey
[[PLVUploadClient sharedClient] loginWithUserId:userId secretKey:secretKey];
……
}
登录失败、或者上传状态的变化，都会通过委托代理的方式通知，代理协议是 PLVUploadClientDelegate。PLVUploadClient 支持多代理，允许多个类同时进行监听。使用 PLVUploadClient 的方法 -addDelegate: 新增代理，使用方法 -removeDelegate: 移除代理。代码示例如下：
#import <PLVVodUploadSDK/PLVVodUploadSDK.h>
@interface UIViewController ()<
PLVUploadClientDelegate
>
@end
@implementation UIViewController
- (void)viewDidLoad {
[super viewDidLoad];
[[PLVUploadClient sharedClient] addDelegate:self];
}
- (void)dealloc {
[[PLVUploadClient sharedClient] removeDelegate:self];
}
- (void)uploadClientLoginError:(NSError *)error {
NSLog(@"登录 SDK 失败，失败原因：%@", error.userInfo);
}
@end
设置 PLVUploadClient 的属性 enableLog，可用于开启控制台的调试日志，默认 enableLog 为 NO。开启日志代码示例如下：
[PLVUploadClient sharedClient].enableLog = YES;
6.5 回调监听
协议 PLVUploadClientDelegate 包含如下几个代理方法，均为 optional 方法，开发者可按需使用：
/**
SDK 登录失败
@param error 失败 error （含错误码和 userInfo ）
*/
- (void)uploadClientLoginError:(NSError *)error;
/**
初始化上传过程中遇到失败
@param error 失败 error （含错误码和 userInfo ）
*/
- (void)prepareUploadError:(NSError *)error fileURL:(NSURL *)fileURL;
/**
启动上传任务失败
@param vid 失败的视频 vid
*/
- (void)startUploadTaskFailure:(NSString *)vid;
/**
某一个任务被加入等待队列
@param video 等待上传的任务（ PLVUploadVideo 对象）
*/
- (void)waitingUploadTask:(PLVUploadVideo *)video;
/**
开始上传某一个任务
@param video 开始上传的任务（ PLVUploadVideo 对象）
*/
- (void)startUploadTask:(PLVUploadVideo *)video;
/**
上传结束
如果成功，error 为 nil
@param video 上传结束的任务（ PLVUploadVideo 对象）
@param error 如果上传失败，回传失败的 NSError 对象指针
*/
- (void)didUploadTask:(PLVUploadVideo *)video error:(NSError * __nullable)error;
/**
上传任务进度变化
注意：该方法运行在后台线程，非主线程！
@param vid 视频 vid
@param progress 上传进度（大于 0 小于 1）
*/
- (void)uploadTask:(NSString *)vid progressChange:(float)progress;
/**
所有任务上传结束（包括成功或失败，不包含被中止/中断的任务）
*/
- (void)didAllUploadTaskComplete;
6.6 上传视频
6.6.1 上传任务初始化
使用 PLVUploadClient 的方法 -uploadVideoAtFileURL: 初始化上传任务，参数 fileURL 是上传文件在本地的存储路径 URL。如果任务初始化成功，该方法会返回 nil，否则会返回一个 NSError 对象。方法声明如下：
/**
上传视频文件
@param fileURL 视频文件本地 URL
@return 如果出错，返回一个 NSError 对象，如果没有，返回 nil
*/
- (NSError *)uploadVideoAtFileURL:(NSURL *)fileURL;
注意，文件上传之前必须先拷贝到想要集成上传 SDK 的 app 的沙盒文件夹中来，否则会因为 iOS 权限限制而导致无法访问，所以 fileURL 必须是 app 的沙盒文件夹路径。
如果任务初始化成功，该方法会返回 nil，否则会返回一个 NSError 对象。还可以通过 delegate 的方式获知初始化失败的原因，对应的 delegate 方法是 -prepareUploadError:fileURL:，示例代码如下：
- (void)prepareUploadError:(NSError *)error fileURL:(NSURL *)fileURL {
NSLog(@"文件 %@ 上传初始化失败", [fileURL path]);
}
6.6.2 上传任务队列
上传任务按照初始化的顺序，依次添加到上传任务队列中，任务队列最大并发数为 3，超过并发数的任务会进入等待状态，直到有别的任务完成。通过监听 delegate 方法 -waitingUploadTask: 和方法 -startUploadTask: 可以知道任务队列的变化：
- (void)waitingUploadTask:(PLVUploadVideo *)video {
// 上传任务 video 被加入队列中，进入等待状态
}
- (void)startUploadTask:(PLVUploadVideo *)video {
// 上传任务 video 被加入队列中，准备开始上传
}
PLVUploadVideo 是上传任务的数据模型，属性 vid 是 PLVUploadVideo 对象的唯一标识。通过 PLVUploadClient 的方法 -videoWithVid: 可获取到上传任务队列中某一个 vid 的 PLVUploadVideo 对象，如果该对象不存在，返回 nil。通过方法 -allUploadVideos 可获取到上传任务队列中的所有任务，这两个方法声明如下：
/**
返回所有上传中或等待上传的任务
status 为 PLVUploadStatusWaiting, PLVUploadStatusUploading, PLVUploadStatusResumable
@return 上传任务数组，数组元素为 PLVUploadVideo 对象
*/
- (NSArray <PLVUploadVideo *>*)allUploadVideos;
/**
在上传中或等待上传的任务队列中，查找指定 vid 的上传任务
@param vid 上传任务对应的视频 vid
@return 上传任务（ PLVUploadVideo 对象）
*/
- (PLVUploadVideo *)videoWithVid:(NSString *)vid;
6.6.3 上传进度监听
PLVUploadVideo 对象中包含一个 block 属性 uploadProgress，可通过该属性监听每一个上传任务的上传进度。代码示例如下：
PLVUploadVideo *video; // 通过前面提到的 delegate 方法返回的
video.uploadProgress = ^(float progress) {
NSLog(@"任务 vid：%@ 的上传进度为 %f", video.vid, progress);
});
也可以通过 delegate 方法 -uploadTask:progressChange: 进行监听，示例代码如下：
- (void)uploadTask:(NSString *)vid progressChange:(float)progress {
NSLog(@"任务 vid：%@ 的上传进度为 %f", vid, progress);
}
6.6.4 上传中止或结束
想要中止上传中的任务，可以调用 PLVUploadClient 的方法 -abortUploadWithVid:，方法声明如下：
/**
中止视频上传
适用于 status 为 PLVUploadStatusWaiting, PLVUploadStatusUploading 的上传任务
@param vid 上传任务的 vid
*/
- (void)abortUploadWithVid:(NSString *)vid;
调用结束后任务会同步中止，被中止的任务不能恢复，不可再续传，只能通过 6.6.1 的方法重新进行任务初始化。
上传结束，不管成功、失败还是被中止，都会收到 delegate 方法 -didUploadTask:error: 的通知。如果成功，error 为 nil。示例代码如下：
- (void)didUploadTask:(PLVUploadVideo *)video error:(NSError *)error {
if (error) {
NSLog(@"任务 vid：%@ 上传失败，失败原因 %@", video.vid, error.userInfo);
} else {
NSLog(@"任务 vid：%@ 上传成功", video.vid);
}
}
当所有加入队列的上传任务都完成时（成功与失败都算完成），delegate 方法 -didAllUploadTaskComplete 会被调用，示例代码如下：
- (void)didAllUploadTaskComplete {
NSLog(@"所有任务上传结束");
}
6.6.5 失败任务续传
上传失败时，如果错误码为 PLVClientErrorCodeOSSErrorCanResumeUpload，可使用 PLVUploadClient 的方法 -retryUploadWithVid:fileURL: 进行续传，方法声明如下：
/**
恢复视频上传
适用于 status 为 PLVUploadStatusResumable 的上传任务
@param vid 上传任务的 vid
@param fileURL 上传文件的 URL
*/
- (void)retryUploadWithVid:(NSString *)vid fileURL:(NSURL *)fileURL;
如果续传任务启动成功，会收到 delegate 方法 -waitingUploadTask: 或方法 -startUploadTask: 的通知，如 6.6.2。如果启动失败，会收到 delegate 方法 -startUploadTaskFailure: 通知。示例代码如下：
- (void)startUploadTaskFailure:(NSString *)vid {
NSLog(@"任务 vid：%@ 上传启动失败", vid);
}
6.6.6 更多上传参数
除了 6.6.1 中提到的 PLVUploadClient 的方法 -uploadVideoAtFileURL:，我们还可以使用如下的方法，为上传任务定义更多的参数：
/**
上传视频文件
@param uploadParameter 参数封装类（包含更多自定义参数）
@return 如果出错，返回一个 NSError 对象，如果没有，返回 nil
*/
- (NSError *)uploadVideoWithMutipleParameter:(PLVUploadParameter *)uploadParameter;
参数 uploadParameter 包含了上传任务的多个自定义参数，包括上传到哪个分类目录下，是否录屏、是否保持源文件、视频文件描述、视频文件标签。除了视频文件的本地存储路径是不可为空的属性，其他属性如果不被设置，都有默认值。PLVUploadParameter 类的各个属性声明如下：
/**
初始化视频上传任务时的参数封装类
*/
@interface PLVUploadParameter : NSObject
/**
待上传的视频文件的本地存储 URL
*/
@property (nonatomic, strong) NSURL *fileURL;
/**
上传目录分类 ID，默认为根目录（ID 为 1）
*/
@property (nonatomic, assign) long long catalogId;
/**
是否录屏，默认为否
*/
@property (nonatomic, assign) BOOL screenRecord;
/**
是否保持源文件，默认为否
*/
@property (nonatomic, assign) BOOL keepSource;
/**
待上传的视频文件描述，可选，不传默认为空
*/
@property (nonatomic, copy) NSString * __nullable videoDescription;
/**
待上传的视频文件标签，可选，不传默认为空
*/
@property (nonatomic, copy) NSString * __nullable videoTag;
@end
6.7 裁剪上传模块
若业务上不需要上传功能，可把上传模块从点播 demo 中移除。移除后，上传功能将无法使用。
6.7.1 修改 Podfile
将 Podfile 中以下两个库注释掉，然后重新执行 pod install。
# pod 'PLVVodUploadSDK'
# pod 'TZImagePickerController', '~> 3.2.0'
6.7.2 移除开源文件
上传模块相关的开源代码位于 PolyvVodSDKDemo/Classes/Upload 文件夹中，将该文件夹中项目中移除。右键菜单选择【Delete】然后选择【Move to Trash】。
6.7.3 上传模块入口移除
上传模块的入口位于首页导航栏右上角，打开 Main.storyboard 文件，将入口按钮删除，如下图：
6.7.4 移除 SDK 注册
将以下代码从 AppDelegate.m 文件的 -application:didFinishLaunchingWithOptions: 方法中移除：
[[PLVUploadUtil sharedUtil] loginUploadClient];
并移除相关的头文件引入：
#import "PLVUploadUtil.h"
6.7.5 移除 framework
此时如果直接运行项目，会报一下错误：
ld: framework not found PLVVodUploadSDK
clang: error: linker command failed with exit code 1 (use -v to see invocation)
打开 TARGETS，选择 Build Phases，在 Link Binary With Libraries 中，将 PLVVodUploadSDK.framework 删除即可：
