6 视频上传

6.1 概述

PLVVodUploadSDK 是易方信息科技股份有限公司提供的可集成于项目中用于 iOS 设备上传视频文件到服务器的 SDK，支持断点续传。使用本 SDK 需要在保利威视频云平台注册账号，并使用该账号进行登录，上传后的视频文件可在该视频平台上进行查看、剪辑、播放、删除等操作。

6.2 文件目录

PLVVodUploadSDK 的文件目录如下，其中红色虚线方框里的是 SDK 的 public 文件：：

视频上传_图1

6.3 开始集成

上传 SDK 支持 iOS 8.0 以上 iOS 设备，需具备 Xcode 10.0 以上开发环境、CocoaPods 1.5.3 以上。关于如何安装 CocoaPods，文档 "2.快速集成" 的 2.2 有讲。

在 Podfile 文件中新增以下内容：

pod 'PLVVodUploadSDK'

然后，使用终端工具切换到项目所在路径下，执行如下命令：

$ pod install

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 文件，将入口按钮删除，如下图：

视频上传_图1

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 删除即可：

视频上传_图3