ApsaraVideo VOD:Upload files using the iOS SDK

Integrate the SDK

Integration methods

Project configuration

After integration, configure your Xcode project:

1. In the menu bar, click Build Setting > Linking > Other Linker Flags.

2. Add -Objc.

Basic settings

Initialize the upload instance

Understand the client-side upload process, then deploy an authorization service for your chosen method:

1. If you use an upload URL and credential, obtain the upload URL and credential from your authorization service.

2. If you use a Security Token Service (STS) token, obtain an STS token from your authorization service.

Initialize the upload instance in two steps:

1. Declare the VODUploadClient property. It cannot be a local variable.

2. Initialize the upload instance.

   Upload URL and credential method

   Note

   • To use an upload URL and credential, call the init method for initialization.

   • Do not set the upload URL and credential during initialization. After the upload starts, the OnUploadStartedListener callback is triggered. Call the setUploadAuthAndAddress:uploadAuth:uploadAddress: method in this callback to set the URL and credential.

   • When the credential expires, the OnUploadTokenExpiredListener callback is triggered. Call the resumeWithAuth method and provide a new upload credential to resume the upload.

   Click to view the code

   // Create a VODUploadClient object
   self.uploader = [VODUploadClient new];
   // weakself
   __weak typeof(self) weakSelf = self;
   // setup callback
   OnUploadFinishedListener FinishCallbackFunc = ^(UploadFileInfo* fileInfo, VodUploadResult* result){
       NSLog(@"Upload finished. Video ID: %@, Image URL: %@", result.videoId, result.imageUrl);
   };
   OnUploadFailedListener FailedCallbackFunc = ^(UploadFileInfo* fileInfo, NSString *code, NSString* message){
       NSLog(@"Upload failed. Error code: %@, Error message: %@", code, message);
   };
   OnUploadProgressListener ProgressCallbackFunc = ^(UploadFileInfo* fileInfo, long uploadedSize, long totalSize) {
       NSLog(@"Upload progress. Uploaded size: %li, Total size: %li", uploadedSize, totalSize);
   };
   OnUploadTokenExpiredListener TokenExpiredCallbackFunc = ^{
       NSLog(@"Upload token expired.");
       // The token expired. Set a new upload credential to resume the upload.
       [weakSelf.uploader resumeWithAuth:@"new upload auth"];
   };
   OnUploadRertyListener RetryCallbackFunc = ^{
       NSLog(@"Upload retry started.");
   };
   OnUploadRertyResumeListener RetryResumeCallbackFunc = ^{
       NSLog(@"Upload retry finished.");
   };
   OnUploadStartedListener UploadStartedCallbackFunc = ^(UploadFileInfo* fileInfo) {
       NSLog(@"Upload started.");
       // Set the upload URL and upload credential.
       [weakSelf.uploader setUploadAuthAndAddress:fileInfo uploadAuth:@"upload auth" uploadAddress:@"upload address"];
   };
   VODUploadListener *listener = [[VODUploadListener alloc] init];
   listener.finish = FinishCallbackFunc;
   listener.failure = FailedCallbackFunc;
   listener.progress = ProgressCallbackFunc;
   listener.expire = TokenExpiredCallbackFunc;
   listener.retry = RetryCallbackFunc;
   listener.retryResume = RetryResumeCallbackFunc;
   listener.started = UploadStartedCallbackFunc;
   // Initialize the uploader.
   [self.uploader init:listener];

   STS token method

   Note

   • To initialize using an STS token, call the init method and pass the temporary STS credentials using the setKeyId:accessKeySecret:secretToken:expireTime:listener: method.

   • When the token expires, the OnUploadTokenExpiredListener callback is triggered. Call the resumeWithToken:accessKeySecret:secretToken:expireTime: method and provide a new STS token to resume the upload.

   Click to view the code

   // Create a VODUploadClient object
   self.uploader = [VODUploadClient new];
   // weakself
   __weak typeof(self) weakSelf = self;
   // setup callback
   OnUploadFinishedListener FinishCallbackFunc = ^(UploadFileInfo* fileInfo,  VodUploadResult* result){
       NSLog(@"Upload finished. Video ID: %@, Image URL: %@", result.videoId, result.imageUrl);
   };
   OnUploadFailedListener FailedCallbackFunc = ^(UploadFileInfo* fileInfo, NSString *code, NSString* message){
       NSLog(@"Upload failed. Error code: %@, Error message: %@", code, message);
   };
   OnUploadProgressListener ProgressCallbackFunc = ^(UploadFileInfo* fileInfo, long uploadedSize, long totalSize) {
       NSLog(@"Upload progress. Uploaded size: %li, Total size: %li", uploadedSize, totalSize);
   };
   OnUploadTokenExpiredListener TokenExpiredCallbackFunc = ^{
       NSLog(@"Upload token expired.");
       // The token expired. Set a new STS token to resume the upload.
       [weakSelf.uploader resumeWithToken:@"STS Key Id" accessKeySecret:@"STS Key Secret" secretToken:@"STS Secret Token" expireTime:@"STS Expire Time"];
   };
   OnUploadRertyListener RetryCallbackFunc = ^{
       NSLog(@"Upload retry started.");
   };
   OnUploadRertyResumeListener RetryResumeCallbackFunc = ^{
       NSLog(@"Upload retry finished.");
   };
   OnUploadStartedListener UploadStartedCallbackFunc = ^(UploadFileInfo* fileInfo) {
       NSLog(@"Upload started.");
   };
   // Initialize
   VODUploadListener *listener = [[VODUploadListener alloc] init];
   listener.finish = FinishCallbackFunc;
   listener.failure = FailedCallbackFunc;
   listener.progress = ProgressCallbackFunc;
   listener.expire = TokenExpiredCallbackFunc;
   listener.retry = RetryCallbackFunc;
   listener.retryResume = RetryResumeCallbackFunc;
   listener.started = UploadStartedCallbackFunc;
   // Set the STS token and listener.
   [self.uploader setKeyId:@"STS Key Id" accessKeySecret:@"STS Key Secret" secretToken:@"STS Secret Token" expireTime:@"STS Expire Time" listener:listener];

3. Set callbacks for key upload events.

   Set the VODUploadListener object with the following callback methods:

   Click to view the code

   /**
    Callback for a successful upload.
    @param fileInfo Information about the uploaded file.
    @param result The upload result.
    */
   typedef void (^OnUploadFinishedListener) (UploadFileInfo* fileInfo, VodUploadResult* result);
   /**
    Callback for a failed upload.
    @param fileInfo Information about the uploaded file.
    @param code The error code.
    @param message The error message.
    */
   typedef void (^OnUploadFailedListener) (UploadFileInfo* fileInfo, NSString *code, NSString * message);
   /**
    Callback for upload progress.
    @param fileInfo Information about the uploaded file.
    @param uploadedSize The size of the uploaded part.
    @param totalSize The total size of the file.
    */
   typedef void (^OnUploadProgressListener) (UploadFileInfo* fileInfo, long uploadedSize, long totalSize);
   /**
    Callback for an expired token.
    If you use an upload URL and credential, call the resumeWithAuth: method to resume the upload.
    If you use an STS token, call the resumeWithToken:accessKeySecret:secretToken:expireTime: method to resume the upload.
    */
   typedef void (^OnUploadTokenExpiredListener) ();
   /**
    Callback for the start of an upload retry.
    */
   typedef void (^OnUploadRertyListener) ();
   /**
    Callback for the end of an upload retry. The upload is resumed.
    */
   typedef void (^OnUploadRertyResumeListener) ();
   /**
    Callback for the start of an upload.
    If you use an upload URL and credential, call the setUploadAuthAndAddress:uploadAuth:uploadAddress: method to set the upload URL and credential.
    @param fileInfo Information about the uploaded file.
    */
   typedef void (^OnUploadStartedListener) (UploadFileInfo* fileInfo);

4. Construct the upload parameters based on the file type, such as audio, video, or image.

   Note

   The upload parameters for audio or video files and image files are slightly different. The client does not support uploading auxiliary media assets.

   Audio and video file parameters

   Construct an upload request function to add an audio or video file to the upload list.

   Click to view the code

   NSString *filePath = [[NSBundle mainBundle] pathForResource:@"video_source_file_name" ofType:@"video_source_file_format_such_as_mp4"];
   VodInfo *vodInfo = [[VodInfo alloc] init];
   vodInfo.title = @"video_name_after_upload";
   vodInfo.desc = @"video_description_after_upload";
   vodInfo.cateId = @(video_category_id);
   vodInfo.tags = @"video_tags_such_as_sports";
   [self.uploader addFile:filePath vodInfo:vodInfo];

   VodInfo description

   Click to view the code

   // Title
   @property (nonatomic, copy) NSString* title;
   // Tags
   @property (nonatomic, copy) NSString* tags;
   // Description
   @property (nonatomic, copy) NSString* desc;
   // Category ID
   @property (nonatomic, strong) NSNumber* cateId;
   // Thumbnail URL (a complete URL that starts with https://)
   @property (nonatomic, copy) NSString* coverUrl;

   After you add a file, the SDK encapsulates the file into an UploadFileInfo object. The structure is as follows:

   Click to view the code

   // Local path of the file
   @property (nonatomic, copy) NSString* filePath;
   // Endpoint
   @property (nonatomic, copy) NSString* endpoint;
   // Bucket
   @property (nonatomic, copy) NSString* bucket;
   // Object
   @property (nonatomic, copy) NSString* object;
   // VodInfo
   @property (nonatomic, strong) VodInfo* vodInfo;

   Note

   To upload a video from a photo album, use the absolute path of the selected video as the file path for the upload.

   Image file parameters

   Click to view the code

   NSString *filePath = [[NSBundle mainBundle] pathForResource:@"image_source_file_name" ofType:@"image_source_file_format_such_as_jpg"];
   VodInfo *imageInfo = [[VodInfo alloc] init];
   imageInfo.title = @"image_name_after_upload";
   imageInfo.desc = @"image_description_after_upload";
   imageInfo.cateId = @(image_category_id);
   imageInfo.tags = @"image_tags_such_as_sports";
   [self.uploader addFile:filePath vodInfo:imageInfo];

5. Start the upload.

   1. Call start to begin the upload.

      [self.uploader start];

      This triggers the OnUploadStartedListener callback. If you use an upload URL and credential, set them in this callback:

      [weakSelf.uploader setUploadAuthAndAddress:fileInfo uploadAuth:weakSelf.uploadAuth uploadAddress:weakSelf.uploadAddress];

   2. After the file starts uploading, the OnUploadProgressListener callback starts to synchronize the upload progress.

      The callback parameters include the size of the uploaded part (uploadedSize) and the total file size (totalSize).

   3. After the file is successfully uploaded, the OnUploadFinishedListener callback returns the uploaded file information (UploadFileInfo) and the upload result (VodUploadResult).

      The VodUploadResult object contains the following properties:

      @property (nonatomic, copy) NSString* videoId;
      @property (nonatomic, copy) NSString* imageUrl;

      Note

      The videoId property is returned only after a video is successfully uploaded using an STS token. The imageUrl property is returned only after an image is successfully uploaded using an STS token. If you use an upload URL and credential, videoId and imageUrl are not returned. You can obtain these values when you request the upload URL and credential.

Execution results

• After a video is uploaded, use the returned videoId to obtain playback URLs.

• After an image is uploaded, an imageUrl is returned. If URL signing is enabled, the imageUrl has a TTL. Configure URL signing.

Queue management

VODUploadClient supports adding multiple files for sequential upload. Use the following methods to manage the upload queue:

• Delete a file from the upload queue. If the file is being uploaded, the upload is canceled, and the next file in the queue starts uploading automatically.

  - (BOOL)deleteFile:(int) index;

• Clear the upload queue. If a file is being uploaded, the upload is canceled.

  - (BOOL)clearFiles;

• Obtain the list of files in the upload queue.

  - (NSMutableArray<UploadFileInfo *> *)listFiles;

• Mark a file as canceled. The file remains in the upload list. If the file is being uploaded, the upload is canceled, and the next file in the queue starts uploading automatically.

  - (BOOL)cancelFile:(int)index;

• Resume the upload of a canceled file. The upload starts automatically.

  - (BOOL)resumeFile:(int)index;

Upload control

• Stop the upload. If a file is being uploaded, the upload is canceled.

  - (BOOL)stop;

  Note

  After stopping, call resumeFile to resume, or clear the queue and re-add the file.

• Pause the upload.

  - (BOOL)pause;

• Resume the upload.

  - (BOOL)resume;

Callback handling

• Upload failure

  If an upload fails, the OnUploadFailedListener callback is triggered. Check the code and message parameters for the failure cause, and display a notification on the page. Error code references: Error codes and OSS error codes.

• Expired credential handling

  When an upload credential or STS token expires, the OnUploadTokenExpiredListener callback is triggered. Request a new credential from your app server and call one of the following methods to resume:

  • Reset the upload credential

    - (BOOL)resumeWithAuth:(NSString *)uploadAuth;

  • Reset the STS token

    - (BOOL)resumeWithToken:(NSString *)accessKeyId
            accessKeySecret:(NSString *)accessKeySecret
                secretToken:(NSString *)secretToken
                 expireTime:(NSString *)expireTime;

• Timeout handling

  On timeout, the OnUploadRertyListener callback is triggered and the upload is retried automatically. You can display a notification on the page or call stop to cancel, or set maxRetryCount to limit retries. When the upload resumes after a retry, the OnUploadRertyResumeListener callback is triggered.

Advanced settings

VODUploadClient supports the following advanced settings:

Upload acceleration

For large files (GB/TB) or cross-region uploads (for example, from the Chinese mainland to the Singapore storage region), enable upload acceleration. After enabling, add the required key-value pair to the UserData JSON string in the vodInfo configuration:

/** 
 Set custom data in VodInfo. 
*/
@property (nonatomic, copy) NSString *UserData;
vodInfo.UserData = "{\"Type\":\"oss\",\"Domain\":\"oss-accelerate.aliyuncs.com\"}";

Parameter descriptions

Upload transcoding

/**
 Specifies whether to transcode the file on the server after upload. The default value is YES. To specify the output format for video transcoding, see Video transcoding.
 */
@property (nonatomic, assign) BOOL transcode;

Timeout and retry

/**
 The maximum number of retries. The default value is INT_MAX.
 */
@property (nonatomic, assign) uint32_t maxRetryCount;
/**
 The timeout period.
 */
@property (nonatomic, assign) NSTimeInterval timeoutIntervalForRequest;

Set the cache folder location

/**
 The location of the cache folder.
 */
@property (nonatomic, copy) NSString * recordDirectoryPath;

Resumable upload

/**
 Specifies whether to record the upload progress for resumable uploads. The default value is YES.
 */
@property (nonatomic, assign) BOOL recordUploadProgress;

Multipart upload

/**
 The part size. The default value is 1024 * 1024.
*/
@property (nonatomic, assign) NSInteger uploadPartSize;

Set the VOD service region

/**
 The VOD region. The default value is "cn-shanghai".
 */
@property (nonatomic, copy) NSString *region;