Getting Started

Last updated: 2020-08-28 17:18:34

    Relevant Resources

    Preparations

    1. You need an Android application; this can be one of your existing projects or a new project.
    2. Make sure that your Android application has a target API level of 15 (Ice Cream Sandwich) or above.
    3. You need a remote address where users can obtain your Tencent Cloud temporary key. For more information on temporary keys, see Practice of Direct Upload for Mobile Apps.

    Step 1. Install the SDK

    Method 1. Automatic integration (recommended)

    Standard SDK

    Add dependencies to build.gradle at the application level (usually under the application module).

    dependencies {
        ...
        // Add this line
        implementation 'com.tencent.qcloud:cosxml:5.5.5'
    }

    If you are using Kotlin for development in your project, you can add our KTX extension package, which provides more user-friendly APIs.

    dependencies {
        ...
        // Add this line
        implementation 'com.tencent.qcloud:cosxml-ktx:5.5.0'
    }

    Simplified SDK

    If you need access only to the basic COS features, such as upload, download, and replication, as well as a minimal SDK size, you may want to use the simplified SDK.

    First, add the Bintray repository location to your build.gradle file at the project level.

    allprojects {
     repositories {
         ...
         // Add a Maven repository
         maven {
             url "https://dl.bintray.com/tencentqcloudterminal/maven"
         }
     }
    }

    Then, add dependencies to build.gradle at the application level (usually under the application module).

    dependencies {
        ...
        // Add this line
        implementation 'com.tencent.qcloud:cosxml-lite:5.5.5'
    }

    Disabling MTA reporting

    We have introduced Tencent Mobile Analytics (TMA) capabilities into the SDK to track down and optimize the SDK quality for a better user experience.

    To disable the MTA feature, add the following statement to build.gradle at the application level (usually under the application module):

    dependencies {
        ...
        implementation ('com.tencent.qcloud:cosxml:x.x.x'){
            // Add this line
            exclude group:'com.tencent.qcloud', module: 'mtaUtils'
        }
    }

    Method 2. Manual integration

    1. Download SDK version

    You can directly download the latest SDK version here, or you can find all of the versions at SDK Releases.

    After downloading and decompressing the file, you can see that it contains multiple JAR or AAR packages which are described as follows. Please choose the ones you want to integrate.

    Required libraries:

    • cosxml: COS protocol implementation
    • qcloud-foundation: foundation library
    • bolts-tasks: third-party task library
    • okhttp: third-party networking library
    • okio: third-party IO library

    Optional libraries:

    • mtaUtils: MTA library for improving the SDK
    • mid-sdk: MTA library for improving the SDK
    • mta-android-sdk: MTA library for improving the SDK
    • LogUtils: log module for improving the SDK
    • quic: QUIC protocol; required if you transfer data over QUIC

    2. Integrate the SDK into your project

    Put your libraries in the libs folder under your application module, and add dependencies to the build.gradle file at the application level (usually under the application module):

    dependencies {
        ...
        // Add this line
        implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
    }

    Step 2. Configure Permissions

    Network permission

    The SDK needs network permission to communicate with the COS server. Please add the following permission statements to the AndroidManifest.xml under your application module:

    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

    Storage permission

    If you need to read and write files from external storage, please add the following permission statements to the AndroidManifest.xml under your application module:

    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

    Note that you need to request dynamic storage permissions at runtime for Android 6.0 (API level 23) or above.

    Step 3. Use the SDK

    1. Obtain a temporary key

    Implement a subclass BasicLifecycleCredentialProvider to request a temporary key and return the result.

    public static class MySessionCredentialProvider
            extends BasicLifecycleCredentialProvider {
    
        @Override
        protected QCloudLifecycleCredentials fetchNewCredentials() 
                throws QCloudClientException {
    
            // First, get the response containing a signature from your temporary key server
    
            // Then, parse the response to get a temporary key
            String tmpSecretId = "COS_SECRETID"; // SecretId of the temporary key
            String tmpSecretKey = "COS_SECRETKEY"; // SecretKey of the temporary key
            String sessionToken = "TOKEN"; // Token of the temporary key
            long expiredTime = 1556183496L;// End timestamp in seconds of the validity period of the temporary key
    
            // We strongly recommend returning the server time as the start time of the signature to avoid request expiration due a large difference between your mobile phone's local time and standard time
            // Return the server time as the start time of the signature
            long startTime = 1556182000L; // Start timestamp in seconds of the validity period of the temporary key
    
            // Finally, return the temporary key object
            return new SessionQCloudCredentials(tmpSecretId, tmpSecretKey,
                    sessionToken, startTime, expiredTime);
        }
    }

    Assumed a class named MySessionCredentialProvider. Now, initialize an instance to provide the key for the SDK.

    QCloudCredentialProvider myCredentialProvider = new MySessionCredentialProvider();

    Using a permanent key for local debugging

    You can use your Tencent Cloud permanent key for local debugging during the development phase. Since this method exposes the key to leakage risks, please be sure to replace it with a temporary key before before launching your application.

    String secretId = "COS_SECRETID"; // The secretId of the permanent key
    String secretKey ="COS_SECRETKEY"; // The secretKey of the permanent key
    
    // keyDuration is the valid duration in seconds of the key in your request
    QCloudCredentialProvider myCredentialProvider = 
        new ShortTimeCredentialProvider(secretId, secretKey, 300);

    2. Initialize a COS Instance

    Use your instance myCredentialProvider for providing keys to initialize a CosXmlService instance.

    CosXmlService provides all APIs for accessing COS. We recommend you use it as an application singleton.

    // Bucket region abbreviation, e.g. ap-guangzhou
    String region = "COS_REGION";
    
    // Create a `CosXmlServiceConfig` object, and modify the default configuration parameters as needed
    CosXmlServiceConfig serviceConfig = new CosXmlServiceConfig.Builder()
            .setRegion(region)
            .isHttps(true) // Set HTTPS as the default request method
            .builder();
    
    // Initialize the COS instance
    CosXmlService cosXmlService = new CosXmlService(context, 
        serviceConfig, myCredentialProvider);

    Note:

    For the COS bucket region abbreviations, see Regions and Access Domain Names.

    Using the KTX package to initialize a COS instance

    The code is shorter for initialization using KTX as shown below:

    val cos = cosService(context = application.applicationContext) {
    
        configuration {
            setRegion("ap-guangzhou")
            isHttps(true)
        }
    
        credentialProvider {
            lifecycleCredentialProvider {
                // fetch credential from backend
                // ...
                return@lifecycleCredentialProvider SessionQCloudCredentials(
                        "temp_secret_id",
                        "temp_secret_key",
                        "session_token",
                        1556183496
                )
            }
        }
    }

    Step 4. Access COS

    Uploading an object

    The SDK supports uploading local files, binary data, URIs, and input streams. The following is an example of uploading a local file.

    // Initialize `TransferConfig`. The default configuration is used here. If you need to customize the configuration, please see the SDK API documentation.
    TransferConfig transferConfig = new TransferConfig.Builder().build();
    // Initialize TransferManager
    TransferManager transferManager = new TransferManager(cosXmlService,
            transferConfig);
    
    String bucket = "examplebucket-1250000000"; // Bucket in the format: BucketName-APPID
    String cosPath = "exampleobject"; // The location identifier of the object in the bucket, i.e. the object key
    String srcPath = new File(context.getCacheDir(), "exampleobject")
            .toString(); // The absolute path of the local file
    // If there is an uploadId for the initialized multipart upload, assign the value of the uploadId here to resume the upload; otherwise, assign null
    String uploadId = null; 
    
    // Upload a file
    COSXMLUploadTask cosxmlUploadTask = transferManager.upload(bucket, cosPath,
            srcPath, uploadId);
    
    // Set the upload progress callback
    cosxmlUploadTask.setCosXmlProgressListener(new CosXmlProgressListener() {
        @Override
        public void onProgress(long complete, long target) {
            // todo Do something to update progress...
        }
    });
    // Set the response callback
    cosxmlUploadTask.setCosXmlResultListener(new CosXmlResultListener() {
        @Override
        public void onSuccess(CosXmlRequest request, CosXmlResult result) {
            COSXMLUploadTask.COSXMLUploadTaskResult cOSXMLUploadTaskResult =
                    (COSXMLUploadTask.COSXMLUploadTaskResult) result;
        }
    
        @Override
        public void onFail(CosXmlRequest request,
                            CosXmlClientException clientException,
                            CosXmlServiceException serviceException) {
            if (clientException != null) {
                clientException.printStackTrace();
            } else {
                serviceException.printStackTrace();
            }
        }
    });
    // Set the job status callback where you can view the job progress
    cosxmlUploadTask.setTransferStateListener(new TransferStateListener() {
        @Override
        public void onStateChanged(TransferState state) {
            // todo notify transfer state
        }
    });

    Using the KTX package to upload an object

    The following sample code shows how to upload using KTX:

    // Use the KTX extension of ViewModel
    // viewModelScope is the built-in coroutine scope of ViewModel
    viewModelScope.launch {
        val `object` = cosObject {
            bucket = cosBucket {
                service = cos
                name = "examplebucket-1250000000"
            }
            key = "exampleObject"
        }
        // Local file example
        val sourceFile = File(appContext.externalCacheDir, "sourceFile")
    
        try {
            // Call the “suspend” function to upload
            val result = `object`.upload(
                localFile = sourceFile,
                progressListener = { complete, target ->
                    Log.d("cosxmlktx", "upload onProgress:" +
                                    " $complete / $target")
                },
                transferStateListener = { state ->
                    Log.d("cosxmlktx", "upload state is : $state")
                }
            )
    
        } catch (e : Exception ) {
            e.printStackTrace()
        }
    
    }

    Note:

    • For more samples, please visit GitHub.
    • You can generate a download URL for the uploaded file using the same key. For detailed directions, see Generating a Pre-Signed Link. Please note that for private-read files, the download URL is only valid for a limited period of time.

    Downloading an object

    // The advanced download API supports checkpoint restart. To do so, a `HEAD` request will be sent first to get file information before download.
    // If you are using a temporary key or accessing with a sub-account, please make sure that your access permission list includes HeadObject.
    
    // Initialize `TransferConfig`. The default configuration is used here. If you need to customize the configuration, please see the SDK API documentation.
    TransferConfig transferConfig = new TransferConfig.Builder().build();
    // Initialize TransferManager
    TransferManager transferManager = new TransferManager(cosXmlService,
            transferConfig);
    
    String bucket = "examplebucket-1250000000"; // Bucket in the format: BucketName-APPID
    String cosPath = "exampleobject"; // The location identifier of the object in the bucket, i.e. the object key
    // Local directory path
    String savePathDir = context.getExternalCacheDir().toString();
    // The file name saved locally. If not specified (null), it will be the same as the COS file name
    String savedFileName = "exampleobject";
    
    Context applicationContext = context.getApplicationContext(); // application
    // context
    COSXMLDownloadTask cosxmlDownloadTask =
            transferManager.download(applicationContext,
            bucket, cosPath, savePathDir, savedFileName);
    
    // Set the download progress callback
    cosxmlDownloadTask.setCosXmlProgressListener(new CosXmlProgressListener() {
        @Override
        public void onProgress(long complete, long target) {
            // todo Do something to update progress...
        }
    });
    // Set the response callback
    cosxmlDownloadTask.setCosXmlResultListener(new CosXmlResultListener() {
        @Override
        public void onSuccess(CosXmlRequest request, CosXmlResult result) {
            COSXMLDownloadTask.COSXMLDownloadTaskResult cOSXMLDownloadTaskResult =
                    (COSXMLDownloadTask.COSXMLDownloadTaskResult) result;
        }
    
        @Override
        public void onFail(CosXmlRequest request,
                            CosXmlClientException clientException,
                            CosXmlServiceException serviceException) {
            if (clientException != null) {
                clientException.printStackTrace();
            } else {
                serviceException.printStackTrace();
            }
        }
    });
    // Set the job status callback where you can view the job progress
    cosxmlDownloadTask.setTransferStateListener(new TransferStateListener() {
        @Override
        public void onStateChanged(TransferState state) {
            // todo notify transfer state
        }
    });

    Use the KTX package to download an object

    The following sample code shows how to download using KTX:

    // Use the KTX extension of ViewModel
    // viewModelScope is the built-in coroutine scope of ViewModel
    viewModelScope.launch {
        val `object` = cosObject {
            bucket = cosBucket {
                service = cos
                name = "examplebucket-1250000000"
            }
            key = "exampleObject"
        }
    
        try {
            // Call the “suspend” function to download
            val result = `object`.download(
                context = appContext,
                destDirectory = appContext.externalCacheDir!!,
                progressListener = { complete, target ->
                    Log.d("cosxmlktx", "download onProgress: " +
                            "$complete / $target")
                },
                transferStateListener = { state ->
                    Log.d("cosxmlktx", "download state is : $state")
                }
            )
    
        } catch (e : Exception ) {
            e.printStackTrace()
        }
    
    }

    Note:

    • For more samples, please visit GitHub.
    • The advanced download API supports checkpoint restart; therefore, a HEAD request will be sent to get file information before download. If you are using a temporary key or accessing with a sub-account, please make sure that your access permission list includes HeadObject.

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help