6 影片上傳

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'

然後，使用終端工具切換到專案所在路徑下，執行如下指令：

$ 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 檔案，將入口按鈕刪除，如下圖：

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