Use the upload SDK for Android to upload files - ApsaraVideo VOD

This topic describes how to use the upload SDK for Android to upload a media file from a local device to ApsaraVideo VOD storage.

Prerequisites

Your Android device runs Android 4.0 or later.
Supported versions: Android 4.0 (API level 14) and later.

Limits

The upload SDK for Android supports uploading only audio and video files. It does not support uploading auxiliary media assets.

Integrate the SDK

1. Install the Android SDK

You can add the Android SDK dependency to your project’s app/build.gradle file.

dependencies {
    implementation 'com.aliyun.video.android:upload:1.7.4'
}

Add the Alibaba Cloud Maven repository URL to the build.gradle file in the root directory.

allprojects {
    repositories {
        maven { url "https://maven.aliyun.com/nexus/content/repositories/releases" }
    }
}

2. Install the OSS Android SDK

The ApsaraVideo VOD upload SDK for Android depends on the OSS SDK. You must install the OSS Android SDK separately. For more information, see Install the OSS Android SDK. Add the dependency to your Gradle project.

Basic configuration

1. Obtain credentials

First, review the client-side upload workflow described in Client-side upload. Then, deploy an authorization service based on your preferred authorization method:

If you choose the upload URL and credential method, obtain an upload URL and credential in your authorization service. For more information, see Obtain an upload URL and credential.
If you choose the STS token method, obtain an STS token in your authorization service. For more information, see Obtain an STS token.

2. Initialize the upload instance

Initialize the upload instance using the upload URL and credential method or the STS token method as needed.

Upload URL and credential method (recommended)

Declare the initialization callback for the upload instance (VODUploadClient).
```
uploader = new VODUploadClientImpl(getApplicationContext());
```

Initialize the upload instance (VODUploadClient).

Note

When you use the upload URL and credential method, call the init method to initialize the upload instance.
In the onUploadStarted callback that is fired after the upload starts, call the setUploadAuthAndAddress(uploadFileInfo, uploadAuth, uploadAddress) method to set the upload URL and credential.
When you upload audio or video files, the onUploadTokenExpired callback is fired if the upload URL and credential expire. Call the resumeWithAuth(uploadAuth) method to resume the upload with a new credential.

Expand to view code

// create VODUploadClient
final VODUploadClient uploader = new VODUploadClientImpl(getApplicationContext());
// setup callback
VODUploadCallback callback = new VODUploadCallback(){
    @Override
    public void onUploadSucceed(UploadFileInfo info) {
        OSSLog.logDebug("onsucceed ------------------" + info.getFilePath());
    }

    @Override
    public void onUploadFailed(UploadFileInfo info, String code, String message) {
        OSSLog.logError("onfailed ------------------ " + info.getFilePath() + " " + code + " " + message);
    }

    @Override
    public void onUploadProgress(UploadFileInfo info, long uploadedSize, long totalSize) {
        OSSLog.logDebug("onProgress ------------------ " + info.getFilePath() + " " + uploadedSize + " " + totalSize);
    }

    @Override
    public void onUploadTokenExpired() {
        OSSLog.logError("onExpired ------------- ");
        // Refresh the upload credential by calling RefreshUploadVideo.
        uploadAuth = "The new upload credential";
        uploader.resumeWithAuth(uploadAuth);
    }

    @Override
    public void onUploadRetry(String code, String message) {
        OSSLog.logError("onUploadRetry ------------- ");
    }

    @Override
    public void onUploadRetryResume() {
        OSSLog.logError("onUploadRetryResume ------------- ");
    }

    @Override
    public void onUploadStarted(UploadFileInfo uploadFileInfo) {
        OSSLog.logError("onUploadStarted ------------- ");
        // The uploadAuth parameter is the upload credential. The uploadAddress parameter is the upload URL.
        uploader.setUploadAuthAndAddress(uploadFileInfo, uploadAuth, uploadAddress);
    }
};
// Initialize the upload instance.
uploader.init(callback);

STS token method

Declare the initialization callback for the upload instance (VODUploadClient).
```
uploader = new VODUploadClientImpl(getApplicationContext());
```

Initialize the upload instance (VODUploadClient).

Note

When you use the STS token method, call the init(accessKeyId, accessKeySecret, secretToken, expireTime, callback) method to initialize the upload instance.
The secretToken initialization parameter is the temporary STS token that you obtained.
If the temporary STS token expires, the onUploadTokenExpired callback is fired. Call the resumeWithToken(accessKeyId, accessKeySecret, secretToken, expireTime) method to resume the upload with a new STS token.

Show code

// create VODUploadClient object
uploader = new VODUploadClientImpl(getApplicationContext());
// setup callback
VODUploadCallback callback = new VODUploadCallback() {
            public void onUploadSucceed(UploadFileInfo info) {
                OSSLog.logDebug("onsucceed ------------------" + info.getFilePath());
            }
            public void onUploadFailed(UploadFileInfo info, String code, String message) {
                OSSLog.logError("onfailed ------------------ " + info.getFilePath() + " " + code + " " + message);
            }
            public void onUploadProgress(UploadFileInfo info, long uploadedSize, long totalSize) {
                OSSLog.logDebug("onProgress ------------------ " + info.getFilePath() + " " + uploadedSize + " " + totalSize);
            }
            public void onUploadTokenExpired() {
                OSSLog.logError("onExpired ------------- ");
                    // Call resumeWithToken after obtaining a new STS token.
                    uploader.resumeWithToken(accessKeyId, accessKeySecret, secretToken, expireTime);
            }
            public void onUploadRetry(String code, String message) {
                OSSLog.logError("onUploadRetry ------------- ");
            }
            public void onUploadRetryResume() {
                OSSLog.logError("onUploadRetryResume ------------- ");
            }
            public void onUploadStarted(UploadFileInfo uploadFileInfo) {
                OSSLog.logError("onUploadStarted ------------- ");
            }
        };
// Initialize the upload instance. If the STS token expires, the onUploadTokenExpired callback fires. Call resumeWithToken to resume the upload with a new STS token. Resumable upload is enabled by default.
uploader.init(accessKeyId, accessKeySecret, secretToken, expireTime, callback);

3. Set the upload status callback class

Set the VODUploadCallback object. This object handles the callbacks for upload status. You can configure the following callback methods:

Show code

/**
 Callback fired when the upload succeeds.
 @param info Information about the uploaded file.
 */
void onUploadSucceed(UploadFileInfo info);
/**
 Callback fired when the upload fails.
 @param info Information about the uploaded file.
 @param code Error code.
 @param message Error message.
 */
 void onUploadFailed(UploadFileInfo info, String code, String message);
/**
 Callback fired when the upload progress changes.
 @param fileInfo Information about the uploaded file.
 @param uploadedSize Size of uploaded parts.
 @param totalSize Total size of the file.
 */
 void onUploadProgress(UploadFileInfo fileInfo, long uploadedSize, long totalSize);
/**
 Callback fired when the upload URL and credential expire.
 If you use the upload URL and credential method, call resumeWithAuth to resume the upload.
 If you use the STS token method, call resumeWithToken to resume the upload.
 */
 void onUploadTokenExpired();
/**
 Callback fired when the system retries the upload.
 */
 void onUploadRetry(String code, String message);
/**
 Callback fired when the system resumes the upload after a retry.
 */
 void onUploadRetryResume ();
/**
 Callback fired when the upload starts.
 If you use the upload URL and credential method, call setUploadAuthAndAddress to specify the upload URL and credential.
 @param fileInfo Information about the uploaded file.
 */
  void onUploadStarted(UploadFileInfo fileInfo);

4. Construct the upload request function

Parameters for audio or video files

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

String filePath = "Path of the file";
VodInfo vodInfo = new VodInfo();
vodInfo.setTitle("Title" + index);
vodInfo.setDesc("Description" + index);
vodInfo.cateId (19);
vodInfo.tags("sports");
uploader.addFile(filePath,vodInfo);

Parameters for image files

Construct an upload request to add an image file to the upload list.

String filePath = "Path of the image";
VodInfo vodInfo = new VodInfo();
vodInfo.setTitle("Title" + index);
vodInfo.setDesc("Description" + index);
vodInfo.cateId (19);
vodInfo.tags("sports");
uploader.addFile(filePath,vodInfo);

Description of vodInfo

// Title.
String title;
// Tags.
List tags;
// Description.
String desc;
// Category ID.
idInteger cateId;
// Thumbnail URL. Must be a complete URL that starts with https://.
String coverUrl;

Note

After you add a file to the upload list, the SDK wraps the file in an UploadFileInfo object. The structure of the object is as follows:

// Local path of the file.
String filePath;
// Endpoint.
String endpoint;
// Bucket.
String bucket;
// Object.
String object;
// VodInfo.
VodInfo vodInfo;

5. Start the upload

Call the start() method to start the upload.
```
void start();
```
This method triggers the onUploadStarted callback. If you use the upload URL and credential method, set the upload URL and credential in this callback. Sample code:
```
void setUploadAuthAndAddress(UploadFileInfo uploadFileInfo, String uploadAuth, String uploadAddress)
```
After the upload starts, the onUploadProgress callback is fired to report the upload progress.
After the upload is successful, the onUploadSucceed callback is fired to return the result. The result includes the videoId and imageUrl properties.

Execution result

After a video is successfully uploaded, the videoId parameter is returned. The value of this parameter is the video ID. You can then obtain a streaming URL to play the video. For more information, see Use playback credentials to play videos.
After an image is successfully uploaded, the imageUrl parameter is returned. The value of this parameter is the image URL. If URL signing is enabled, the image URL expires after a specified period. For more information, see Configure URL signing.

6. Destroy

Call the release() method to release the upload instance. This helps prevent memory and thread leaks.

void release();

Advanced features

Upload acceleration

The VODUploadClient upload instance supports upload acceleration.

To upload large files (in gigabytes or terabytes) or upload files across regions, such as from the Chinese mainland to the Singapore storage region, you can enable the upload acceleration feature. For more information, see Enable upload acceleration. After you enable upload acceleration, you must add the corresponding UserData string assignment, including the appropriate key-value pairs (passed as a JSON string), to the vodInfo configuration of the upload instance. Sample syntax:

vodInfo.setUserData("{\"Type\":\"oss\",\"Domain\":\"oss-accelerate.aliyuncs.com\"}");

Parameters

Name	Type	Description
Type	string	Type of upload acceleration. Only OSS is supported.
Domain	string	Accelerated domain name of the bucket. Default value: https. Note An accelerated endpoint assigned after you enable upload acceleration, such as vod-*******.oss-accelerate.aliyuncs.com.

Queue management

The VODUploadClient upload instance supports sequential uploads of multiple files. You can use the following methods to manage the upload queue:

Note

The VODUploadClient object supports uploading multiple files at the same time. However, if you use upload URLs and credentials, you must configure each file separately. Because the code for multi-file uploads is complex, we recommend that you upload one file at a time.

Removes a file from the upload queue. If the file is being uploaded, the upload is canceled and the upload of the next file automatically starts.
```
void deleteFile(int index)
```
Clears the upload queue. If a file is being uploaded, the upload is canceled.
```
void clearFiles()
```
Retrieves the upload queue.
```
List<UploadFileInfo> listFiles()
```
Marks a file as canceled without removing it from the upload queue. If the file is being uploaded, the upload is canceled and the upload of the next file automatically starts.
```
cancelFile(int index)
```
Resumes the upload of a canceled file. The upload automatically starts.
```
resumeFile(int index)
```

Upload control

The VODUploadClient upload instance supports the following upload control methods:

Stops the upload. If a file is being uploaded, the upload is canceled.
```
void stop();
```
Note
To resume the upload after you stop it, call resumeFile to resume the file upload, or clear the queue and add the file again.
Pauses the upload.
```
void pause();
```
Resumes the upload.
```
void resume();
```

Callback handling

The VODUploadClient upload instance supports the following callbacks:

Upload Failed

The onUploadFailed callback is fired when the upload fails. You can check the code and message parameters to identify the cause of the failure and display a prompt on the page. For more information about error codes, see Error codes and OSS error codes.
Upload URL and Credentials Expiration

The onUploadTokenExpired callback is fired when the upload credential expires. You must request a new upload credential from your AppServer and call a method to resume the upload with the new credential.

Note
You must set the refreshed upload credential in the callback.
Upload timeout

When the upload times out, the uploadRetry callback is fired and the system automatically retries the upload. You can display a prompt on the page or call the cancel method to stop the upload. You can also set the maxRetryCount property to specify the maximum number of retries. If the upload can continue after a retry, the uploadRetryResume callback is fired and the upload resumes.

Timeout handling

The VODUploadClient upload instance lets you set the maximum number of retries for upload timeouts.

/**
Set the maximum number of retries for upload timeouts. Default value: INT_MAX.
 */
void setVodHttpClientConfig(VodHttpClientConfig var);

Multipart upload

The upload instance (VODUploadClient) lets you specify a file size threshold for multipart uploads. If the size of a file exceeds the partSize value, a multipart upload is performed.

/**
 Part size. Default value: 1024 × 1024. Unit: bytes. If a file exceeds the partSize value, multipart upload is used.
*/
void setPartSize(long partSize);

Storage location

The VODUploadClient upload instance lets you specify a storage location for uploaded files. If no storage location is specified, files are uploaded to the default location. You must enable and configure the storage location before you can upload files to it. For more information, see Overview.

/**
* Specify a storage location for the file. Log on to the ApsaraVideo VOD console. In the navigation pane on the left, choose Configuration Management > Media Management > Storage. On the Storage page, view the storage location.
*/
void setStorageLocation(String storageLocation);

Transcoding

The VODUploadClient upload instance lets you configure transcoding by specifying a transcoding template group ID.

/**
* Set the ID of the transcoding template group. Log on to the ApsaraVideo VOD console. In the navigation pane on the left, choose Configuration Management > Media Processing > Transcoding Template Groups. On the Transcoding Template Groups page, view the ID.
*/
void setTemplateGroupId(String templateGroupId);

The VODUploadClient upload instance lets you configure a workflow by specifying a workflow ID.

/**
* Set the ID of the workflow. Log on to the ApsaraVideo VOD console. In the navigation pane on the left, choose Configuration Management > Media Processing > Workflow Management. On the Workflow Management page, view the ID.
*/
void setWorkflowId(String workflowId);

Important

If you set both a transcoding template group ID and a workflow ID, the workflow configuration takes precedence.

Resumable upload

The client-side upload SDK supports resumable uploads. Make sure that the following method is set to true.

/**
 * Enable recording of upload progress for resumable upload. Default value: true. The upload SDK automatically resumes interrupted uploads only when this parameter is set to true. If set to false, resumable upload is disabled.
 */
void setRecordUploadProgressEnabled(boolean var1);

Region setting

The VODUploadClient upload instance lets you set the ApsaraVideo VOD service region.

/**
 Specify the ApsaraVideo VOD service region. Default value: cn-shanghai.
 */
void setRegion(String var);