Getting Started

Last updated: 2020-09-07 16:36:14

    Relevant Resources

    Preparations

    1. Prepare an iOS application, which can be your existing project or a new empty project.
    2. Make sure that the application is constructed based on the SDK for iOS 8.0 or above.
    3. Prepare a remote address that can be used to get the Tencent Cloud temporary key. For more information on the temporary key, please see Practice of Direct Upload for Mobile Apps.

    Step 1. Install the SDK

    Method 1. Use CocoaPods for integration (recommended)

    Standard SDK

    Add the following content to the Podfile file in your project:

    pod 'QCloudCOSXML'

    Disabling MTA reporting

    In order to continuously track and optimize the SDK quality and deliver a better user experience, we introduced Mobile Tencent Analytics (MTA) into the SDK.

    If you want to disable this feature, add the following content to the Podfile file in your project

    pod 'QCloudCOSXML/WithoutMTA'

    Lite SDK

    If you use only upload and download features and want to keep the SDK size small, you can use the Lite SDK, which does not have the MTA feature.

    The Lite SDK is implemented by using the Subspec feature of CocoaPods, so it can only be automatically integrated. Add the following content to the Podfile file in your project:

    pod 'QCloudCOSXML/Transfer'

    Method 2. Manually integrate

    You can download the latest release package here. For all release packages on historical versions, please see SDK Releases.

    1. Import the binary library

    Drag QCloudCOSXML.framework, QCloudCore.framework, and libmtasdk.a to your project.

    Add the following dependent libraries:

    • CoreTelephony
    • Foundation
    • SystemConfiguration
    • libc++.tbd

    2. Configure the project

    Set "Other Linker Flags" in "Build Settings" and add the following parameters:

    -ObjC
    -all_load

    Step 2. Start to use

    1. Import the header file

    Objective-c

    #import <QCloudCOSXML/QCloudCOSXML.h>

    swift

    import QCloudCOSXML

    For the Lite SDK, import the following:

    Objective-c

    #import <QCloudCOSXML/QCloudCOSXMLTransfer.h>

    swift

    import QCloudCOSXMLTransfer

    2. Create COS service instances

    Method 1. Get the temporary key to authorize the request (recommended)

    We recommend you place the initialization process in AppDelegate. The following two protocols need to be implemented:

    • QCloudSignatureProvider
    • QCloudCredentailFenceQueueDelegate

    We provide a QCloudCredentailFenceQueue scaffold to cache and reuse the temporary key.

    We recommend you design the COS service instances QCloudCOSXMLService and QCloudCOSTransferMangerService as program singletons.

    Please see the following complete sample code:

    Objective-c

    //AppDelegate.m
    // `AppDelegate` must follow the `QCloudSignatureProvider` and 
    // `QCloudCredentailFenceQueueDelegate` protocols
    
    @interface AppDelegate()<QCloudSignatureProvider, QCloudCredentailFenceQueueDelegate>
    
    // Scaffold instance
    @property (nonatomic) QCloudCredentailFenceQueue* credentialFenceQueue;
    
    @end
    
    @implementation AppDelegate
    
    - (BOOL)application:(UIApplication * )application 
            didFinishLaunchingWithOptions:(NSDictionary * )launchOptions {
        QCloudServiceConfiguration* configuration = [QCloudServiceConfiguration new];
        QCloudCOSXMLEndPoint* endpoint = [[QCloudCOSXMLEndPoint alloc] init];
        // Service region abbreviation; for example, it is `ap-guangzhou` for the Guangzhou region
        endpoint.regionName = @"COS_REGION";
        // Use HTTPS
        endpoint.useHTTPS = true;
        configuration.endpoint = endpoint;
        // The key is provided by yourself
        configuration.signatureProvider = self;
        // Initialize COS service instances
        [QCloudCOSXMLService registerDefaultCOSXMLWithConfiguration:configuration];
        [QCloudCOSTransferMangerService registerDefaultCOSTransferMangerWithConfiguration:
            configuration];
    
        // Initialize the temporary key scaffold
        self.credentialFenceQueue = [QCloudCredentailFenceQueue new];
        self.credentialFenceQueue.delegate = self;
    
        return YES;
    }
    
    - (void) fenceQueue:(QCloudCredentailFenceQueue * )queue requestCreatorWithContinue:(QCloudCredentailFenceQueueContinue)continueBlock
    {
        // Get the temporary key from the backend server synchronously
        //...
    
        QCloudCredential* credential = [QCloudCredential new];
        // Temporary key's `SecretId`
        credential.secretID = @"COS_SECRETID";
        // Temporary key's `SecretKey`
        credential.secretKey = @"COS_SECRETKEY";
        // Temporary key's `Token`
        credential.token = @"COS_TOKEN";
        // We strongly recommend you return the server time as the start time of the signature
        // This is to avoid signature errors caused by large deviation of the mobile phone's local time from the server time
        credential.startDate = [[[NSDateFormatter alloc] init] 
            dateFromString:@"startTime"]; // Unit: second
        credential.experationDate = [[[NSDateFormatter alloc] init] 
            dateFromString:@"expiredTime"];
    
        QCloudAuthentationV5Creator* creator = [[QCloudAuthentationV5Creator alloc]
            initWithCredential:credential];
        continueBlock(creator, nil);
    }
    
    // Entry of the method for getting signature. Here shows the process of getting the temporary key and calculating the signature
    // You can also customize the signature calculation process
    - (void) signatureWithFields:(QCloudSignatureFields*)fileds
                         request:(QCloudBizHTTPRequest*)request
                      urlRequest:(NSMutableURLRequest*)urlRequst
                       compelete:(QCloudHTTPAuthentationContinueBlock)continueBlock
    {
        [self.credentialFenceQueue performAction:^(QCloudAuthentationCreator *creator, 
            NSError *error) {
            if (error) {
                continueBlock(nil, error);
            } else {
                QCloudSignature* signature =  [creator signatureForData:urlRequst];
                continueBlock(signature, nil);
            }
        }];
    }
    
    
    @end

    Swift

    //AppDelegate.swift
    // `AppDelegate` must follow the `QCloudSignatureProvider` and 
    // `QCloudCredentailFenceQueueDelegate` protocols
    
    class AppDelegate: UIResponder, UIApplicationDelegate,
        QCloudSignatureProvider, QCloudCredentailFenceQueueDelegate {
    
        var credentialFenceQueue:QCloudCredentailFenceQueue?;
    
        func application(_ application: UIApplication, 
            didFinishLaunchingWithOptions launchOptions: 
            [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
            let config = QCloudServiceConfiguration.init();
    
            let endpoint = QCloudCOSXMLEndPoint.init();
            // Service region abbreviation; for example, it is `ap-guangzhou` for the Guangzhou region
            endpoint.regionName = "COS_REGION";
            // Use HTTPS
            endpoint.useHTTPS = true;
            config.endpoint = endpoint;
            // The key is provided by yourself
            config.signatureProvider = self;
    
            // Initialize COS service instances
            QCloudCOSXMLService.registerDefaultCOSXML(with: config);
            QCloudCOSTransferMangerService.registerDefaultCOSTransferManger(
                with: config);
    
            // Initialize the temporary key scaffold
            self.credentialFenceQueue = QCloudCredentailFenceQueue.init();
            self.credentialFenceQueue?.delegate = self;
    
            return true
        }
    
        func fenceQueue(_ queue: QCloudCredentailFenceQueue!, 
            requestCreatorWithContinue continueBlock: 
            QCloudCredentailFenceQueueContinue!) {
            // Get the temporary key from the backend server synchronously
            //...
    
            let credential = QCloudCredential.init();
            // Temporary key's `SecretId`
            credential.secretID = "COS_SECRETID";
            // Temporary key's `SecretKey`
            credential.secretKey = "COS_SECRETKEY";
            // Temporary key's `Token`
            credential.token = "COS_TOKEN";
            // We strongly recommend you return the server time as the start time of the signature
            // This is to avoid signature errors caused by large deviation of the mobile phone's local time from the server time
            credential.startDate = DateFormatter().date(from: "startTime");
            // Here, the unit of the returned time is second
            credential.experationDate = DateFormatter().date(from: "expiredTime");
    
            let auth = QCloudAuthentationV5Creator.init(credential: credential);
            continueBlock(auth,nil);
        }
    
        // Entry of the method for getting signature. Here shows the process of getting the temporary key and calculating the signature
        // You can also customize the signature calculation process
        func signature(with fileds: QCloudSignatureFields!, 
            request: QCloudBizHTTPRequest!, 
            urlRequest urlRequst: NSMutableURLRequest!, 
            compelete continueBlock: QCloudHTTPAuthentationContinueBlock!) {
            self.credentialFenceQueue?.performAction({ (creator, error) in
                if error != nil {
                    continueBlock(nil,error!);
                }else{
                    let signature = creator?.signature(forData: urlRequst);
                    continueBlock(signature,nil);
                }
            })
        }
    }

    Note:

    • For the abbreviations of different bucket regions, please see Regions and Access Domain Names.
    • We recommend you request data over HTTPS, but if you want to use HTTP, to ensure that the application can run on iOS 9.0 or above, you need to enable transfer over HTTP for the application. For detailed directions, please see Apple's official document Preventing Insecure Network Connections.

    If your QCloudServiceConfiguration is changed, you can register a new instance as follows:

    + (QCloudCOSTransferMangerService*) registerCOSTransferMangerWithConfiguration:(QCloudServiceConfiguration*)configuration withKey:(NSString*)key;

    Method 2. Use a permanent key for local debugging

    You can use a Tencent Cloud permanent key for local debugging during the development. As this method may disclose your key, please change to the temporary key method before launching your application.

    Implementation of the QCloudCredentailFenceQueueDelegate protocol is optional if you use a permanent key.

    Objective-C

    - (void) signatureWithFields:(QCloudSignatureFields*)fileds
                         request:(QCloudBizHTTPRequest*)request
                      urlRequest:(NSMutableURLRequest*)urlRequst
                       compelete:(QCloudHTTPAuthentationContinueBlock)continueBlock
    {
    
        QCloudCredential* credential = [QCloudCredential new];
        credential.secretID = @"COS_SECRETID"; // Permanent key's `SecretId`
        credential.secretKey = @"COS_SECRETKEY"; // Permanent key's `SecretKey`
    
        // Calculate the signature with a permanent key
        QCloudAuthentationV5Creator* creator = [[QCloudAuthentationV5Creator alloc] 
            initWithCredential:credential];
        QCloudSignature* signature = [creator signatureForData:urlRequst];
        continueBlock(signature, nil);
    }

    Swift

    func signature(with fileds: QCloudSignatureFields!, 
                    request: QCloudBizHTTPRequest!, 
                    urlRequest urlRequst: NSMutableURLRequest!, 
                    compelete continueBlock: QCloudHTTPAuthentationContinueBlock!) {
        let credential = QCloudCredential.init();
        credential.secretID = "COS_SECRETID"; // Permanent key's `SecretId`
        credential.secretKey = "COS_SECRETKEY"; // Permanent key's `SecretKey`
    
        // Calculate the signature with a permanent key
        let auth = QCloudAuthentationV5Creator.init(credential: credential);
        let signature = auth?.signature(forData: urlRequst)
        continueBlock(signature,nil);
    }

    Method 3. Use the signature calculated on the backend to authorize the request

    Implementation of the QCloudCredentailFenceQueueDelegate protocol is optional if the signature is generated on the backend.

    Objective-C

    - (void) signatureWithFields:(QCloudSignatureFields*)fileds
                         request:(QCloudBizHTTPRequest*)request
                      urlRequest:(NSMutableURLRequest*)urlRequst
                       compelete:(QCloudHTTPAuthentationContinueBlock)continueBlock
    {
        // Signature expiration time
        NSDate *expiration = [[[NSDateFormatter alloc] init] 
                                dateFromString:@"expiredTime"];
        QCloudSignature *sign = [[QCloudSignature alloc] initWithSignature:
            @"Signature calculated on backend" expiration:expiration];
        continueBlock(signature, nil);
    }

    Swift

    func signature(with fileds: QCloudSignatureFields!, 
                    request: QCloudBizHTTPRequest!, 
                    urlRequest urlRequst: NSMutableURLRequest!, 
                    compelete continueBlock: QCloudHTTPAuthentationContinueBlock!) {
        // Signature expiration time
        let expiration = DateFormatter().date(from: "expiredTime");
        let sign = QCloudSignature.init(signature: "signature calculated on backend", 
                    expiration: expiration);
        continueBlock(signature,nil);
    }

    Step 3. Access COS

    Uploading object

    The SDK allows you to upload local files and binary data (NSData). The following uses local file upload as an example:

    Objective-C

    QCloudCOSXMLUploadObjectRequest* put = [QCloudCOSXMLUploadObjectRequest new];
    // Local file path
    NSURL* url = [NSURL fileURLWithPath:@"file URL"];
    // Bucket name in the format of `BucketName-APPID`
    put.bucket = @"examplebucket-1250000000";
    // Object key, which is the full path of the object in COS. If the path contains a directory, its format will be "dir1/object1"
    put.object = @"exampleobject";
    // Content of the object to be uploaded. You can pass in variables in `NSData*` or `NSURL*` type
    put.body =  url;
    // Listen on the upload progress
    [put setSendProcessBlock:^(int64_t bytesSent,
                                int64_t totalBytesSent,
                                int64_t totalBytesExpectedToSend) {
        //      bytesSent                   Number of sent bytes
        //      totalBytesSent              Total number of bytes sent in this upload
        //      totalBytesExpectedToSend    Target number of bytes for this upload
    }];
    
    // Listen on the upload result
    [put setFinishBlock:^(id outputObject, NSError *error) {
        // You can get information such as `etag` or custom header in the response from `outputObject`
        NSDictionary * result = (NSDictionary *)outputObject;
    }];
    
    [[QCloudCOSTransferMangerService defaultCOSTransferManager] UploadObject:put];

    Note:

    • For more complete samples, please visit GitHub.
    • After an object is uploaded, you can use the same key to generate a file download link as instructed in Generating Pre-signed Link. However, please note that if your file is set to private-read, the download link will only be valid for a certain period of time.

    Swift

    let put:QCloudCOSXMLUploadObjectRequest = QCloudCOSXMLUploadObjectRequest<AnyObject>();
    // Bucket name in the format of `BucketName-APPID`
    put.bucket = "examplebucket-1250000000";
    // Object key, which is the full path of the object in COS. If the path contains a directory, its format will be "dir1/object1"
    put.object = "exampleobject";
    // Content of the object to be uploaded. You can pass in variables in `NSData*` or `NSURL*` type
    put.body = NSURL.fileURL(withPath: "Local File Path") as AnyObject;
    
    // Listen on the upload result
    put.setFinish { (result, error) in
        // Get the upload result
        if error != nil{
            print(error!);
        }else{
            print(result!);
        }
    }
    
    // Listen on the upload progress
    put.sendProcessBlock = { (bytesSent, totalBytesSent,
        totalBytesExpectedToSend) in
        //      bytesSent                   Number of sent bytes
        //      totalBytesSent              Total number of bytes sent in this upload
        //      totalBytesExpectedToSend    Target number of bytes for this upload
    };
    // Set upload parameters
    put.initMultipleUploadFinishBlock = {(multipleUploadInitResult, resumeData) in
        // After the initialization of the multipart upload is completed, this block will be called back, where you can get the `resumeData`
        // `resumeData` can be used to generate a new multipart upload request
        let resumeUploadRequest = QCloudCOSXMLUploadObjectRequest<AnyObject>
            .init(request: resumeData as Data?);
    }
    
    QCloudCOSTransferMangerService.defaultCOSTransferManager().uploadObject(put);

    Note:

    • For more complete samples, please visit GitHub.
    • After an object is uploaded, you can use the same key to generate a file download link as instructed in Generating Pre-signed Link. However, please note that if your file is set to private-read, the download link will only be valid for a certain period of time.

    Downloading object

    Objective-C

    QCloudCOSXMLDownloadObjectRequest * request = [QCloudCOSXMLDownloadObjectRequest new];
    
    // Bucket name in the format of `BucketName-APPID`
    request.bucket = @"examplebucket-1250000000";
    // Object key, which is the full path of the object in COS. If the path contains a directory, its format will be "dir1/object1"
    request.object = @"exampleobject";
    
    // Set the download path URL; if this is set, the file will be downloaded to the specified path
    request.downloadingURL = [NSURL fileURLWithPath:@"Local File Path"];
    
    // Listen on the download result
    [request setFinishBlock:^(id outputObject, NSError *error) {
        // `outputObject` contains all HTTP response headers
        NSDictionary* info = (NSDictionary *) outputObject;
    }];
    
    // Listen on the download progress
    [request setDownProcessBlock:^(int64_t bytesDownload,
                                    int64_t totalBytesDownload,
                                    int64_t totalBytesExpectedToDownload) {
        //      bytesDownload                   Number of downloaded bytes
        //      totalBytesDownload              Total number of bytes received in this download
        //      totalBytesExpectedToDownload    Target number of bytes for this download
    }];
    
    [[QCloudCOSTransferMangerService defaultCOSTransferManager] DownloadObject:request];

    Note:

    For more complete samples, please visit GitHub.

    Swift

    let request : QCloudCOSXMLDownloadObjectRequest = QCloudCOSXMLDownloadObjectRequest();
    
    // File bucket
    request.bucket = "examplebucket-1250000000";
    // Object key
    request.object = "exampleobject";
    
    // Set the download path URL; if this is set, the file will be downloaded to the specified path
    request.downloadingURL = NSURL.fileURL(withPath: "Local File Path") as URL?;
    
    // Listen on the download progress
    request.sendProcessBlock = { (bytesDownload, totalBytesDownload,
        totalBytesExpectedToDownload) in
        //      bytesDownload                   Number of downloaded bytes
        //      totalBytesDownload              Total number of bytes received in this download
        //      totalBytesExpectedToDownload    Target number of bytes for this download
    }
    
    // Listen on the download result
    request.finishBlock = { (copyResult, error) in
        if error != nil{
            print(error!);
        }else{
            print(copyResult!);
        }
    }
    
    QCloudCOSTransferMangerService.defaultCOSTransferManager().downloadObject(request);

    Note:

    For more complete samples, please visit GitHub.

    Was this page helpful?

    Was this page helpful?

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