tencent cloud

Getting Started
Last updated: 2026-01-05 17:33:22
Getting Started
Last updated: 2026-01-05 17:33:22

Relevant Resources

For the repository of the SDK source code, see: XML iOS SDK.
Quick download link for SDK: XML iOS SDK.
For a sample Demo, see: XML iOS SDK Demo.
For SDK interfaces and parameter documentation, see SDK API Reference.
For all sample code in the SDK documentation, see SDK Code Samples.
For the change log of the SDK, see: ChangeLog.
For SDK FAQs, see: iOS SDK FAQs.

Environment Configuration and Preparation

1. You need an iOS application. This application can be your existing project or a new project.
2. The SDK supports iOS version 8.0 and above. Before installation, check the minimum system version supported by your project.
3. You need to obtain an API key for Tencent Cloud. This key is a prerequisite for your use of the various features of the COS SDK.
Note:
Secret keys are credentials for authenticating identity when making requests to COS, including temporary secret keys and permanent secret keys. Temporary secret keys are suitable for temporary authorization scenarios such as frontend direct uploads, while permanent secret keys are suitable for trusted users in scenarios requiring high security.
It is recommended that users use temporary secret keys to call the SDK, further enhancing security through temporary authorization. When applying for temporary secret keys, please follow the Principle of Least Privilege to prevent leakage of resources beyond the target bucket or objects.
If you must use permanent secret keys, it is recommended that you follow the Principle of Least Privilege to restrict the scope of permissions for these keys.

Installing the SDK

Method 1: Using Cocoapods for Integration (Recommended)

COS SDK has three editions: Standard Edition, Lite Edition, and Beacon-Free Edition.
Standard Edition: Includes all features of the COS API and provides the most comprehensive functionality.
Lite Edition: only includes the file upload/download feature of COS (If you only use the upload and download features and have high requirements for the SDK size, it is recommended to use the Lite Edition SDK).
Beacon-Free Edition: Removes the data reporting service for Tencent's Beacon on the basis of the Standard Edition.
Note:
In order to continuously track and optimize the quality of the SDK and provide you with a better user experience, we have integrated the Tencent Beacon SDK. Tencent Beacon only monitors the request performance on the COS side and does not report business-side data.
In the Podfile of your project, add:
Standard Edition
Lite Edition
Beacon-Free Edition
pod 'QCloudCOSXML'
pod 'QCloudCOSXML/Transfer'
pod 'QCloudCOSXML/Slim'
Note:
The Lite Edition SDK and Beacon-Free Edition SDK are implemented using the Subspec feature of Cocoapods, and therefore currently only support integration via the automatic integration approach.
Note:
When integrating with Pod in a Swift project, you need to add `use_frameworks!` in the podfile.
After integrating the SDK using Pod, if you encounter a permission denied error during compilation, search for ENABLE_USER_SCRIPT_SANDBOXING in Build Settings and set it to NO, as shown in the figure below:


Option 2: Manual Integration

We have provided all official packages of the SDK since its release in SDK Releases. For integration methods, refer to the following:
1. Drag QCloudCOSXML.framework, QCloudCore.framework, QCloudTrack.framework, and COSBeaconAPI_Base.framework into your project.

Note:
QCloudCore.framework and QCloudCOSXML.framework are core components of the SDK and are mandatory.
COSBeaconAPI_Base.framework and QCloudTrack.framework are log reporting components and are optional dependencies.
2. Add the following system dependencies:
CoreTelephony
Foundation
SystemConfiguration
libc++.tbd
3. In the Build Setting of the project, configure Other Linker Flags and add the following parameters:
-ObjC

Note:
The SDK provides a packaging script that allows you to package according to your business needs (this script depends on Cocoapods; please ensure your development environment has Cocoapods installed). The packaging procedure is as follows:
1. Download the source code: git clone https://github.com/tencentyun/qcloud-sdk-ios.
2. Run the packaging script: source package.sh.
3. Drag the packaged artifacts into your project, then follow the steps for manual integration as described above.
iOS: Drag the artifacts from the ios folder into your project.
macOS: Drag the artifacts from the osx folder into your project.


Initialize COS Service

Import Header Files

Objective-C
Swift
Standard Edition
Lite Edition
Beacon-Free Edition
#import <QCloudCOSXML/QCloudCOSXML.h>
#import <QCloudCOSXML/QCloudCOSXMLTransfer.h>
#import <QCloudCOSXML/QCloudCOSXML.h>
Standard Edition
Lite Edition
Beacon-Free Edition
import QCloudCOSXML
import QCloudCOSXML
import QCloudCOSXML

Initialize COS

Note:
Before using the COS SDK, we need to create a bucket in the console. For creation guidance, see Console Quick Start.
Initialize the COS SDK after the application starts.
Objective-C
Swift
SwiftUI
//AppDelegate.m
@interface AppDelegate()
@end

@implementation AppDelegate

- (BOOL)application:(UIApplication * )application
didFinishLaunchingWithOptions:(NSDictionary * )launchOptions {
QCloudServiceConfiguration* configuration = [QCloudServiceConfiguration new];
QCloudCOSXMLEndPoint* endpoint = [[QCloudCOSXMLEndPoint alloc] init];
// You can view the abbreviation of the bucket region in the console: https://console.tencentcloud.com/cos5/bucket
// For example, the Guangzhou region is ap-guangzhou. For the full list of COS regions, see https://www.qcloud.com/document/product/436/6224
endpoint.regionName = @"COS_REGION";
// Use HTTPS
endpoint.useHTTPS = true;
configuration.endpoint = endpoint;
// Example of Initializing the COS Service
[QCloudCOSXMLService registerDefaultCOSXMLWithConfiguration:configuration];
[QCloudCOSTransferMangerService registerDefaultCOSTransferMangerWithConfiguration:
configuration];
return YES;
}

@end
//AppDelegate.swift
class AppDelegate: UIResponder, UIApplicationDelegate {

func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions:
[UIApplication.LaunchOptionsKey: Any]?) -> Bool {
let config = QCloudServiceConfiguration.init();
let endpoint = QCloudCOSXMLEndPoint.init();
// The abbreviation of the bucket region can be viewed in the console: https://console.tencentcloud.com/cos5/bucket
// For example, the Guangzhou region is ap-guangzhou. For the full list of COS regions, see https://www.qcloud.com/document/product/436/6224.
endpoint.regionName = "COS_REGION";
// Use HTTPS
endpoint.useHTTPS = true;
config.endpoint = endpoint;

// Example of Initializing the COS Service
QCloudCOSXMLService.registerDefaultCOSXML(with: config);
QCloudCOSTransferMangerService.registerDefaultCOSTransferManger(
with: config);
return true
}
}
import SwiftUI
import QCloudCOSXML

@main
struct SwiftUIDemoApp: App {
init() {
// Call SDK configuration during application initialization.
COSManager.shared.setupCOSSDK();
}
var body: some Scene {
WindowGroup {
ContentView()
}
}
}

class COSManager: NSObject {
static let shared = COSManager()
private override init() {}
func setupCOSSDK() {
let config = QCloudServiceConfiguration.init();
let endpoint = QCloudCOSXMLEndPoint.init();
// The abbreviation of the bucket region can be viewed in the console: https://console.tencentcloud.com/cos5/bucket
// For example, the Guangzhou region is ap-guangzhou. For the full list of COS regions, see https://www.qcloud.com/document/product/436/6224.
endpoint.regionName = "COS_REGION";
// Use HTTPS
endpoint.useHTTPS = true;
config.endpoint = endpoint;
// Example of Initializing the COS Service
QCloudCOSXMLService.registerDefaultCOSXML(with: config);
QCloudCOSTransferMangerService.registerDefaultCOSTransferManger(with: config);
}
}

Configure API Access Key

Access keys are a prerequisite for COS SDK to access all services. Keys are categorized into: permanent keys and temporary keys. The SDK provides multiple methods to set keys, as follows:
Temporary keys: Associated with each COS request, these are set by the client when a request is initiated and take precedence over the method of setting keys via callback.
Key callback: The SDK fetches access keys via callback upon first use and when cached keys are nearly expired.
Note:
It is strongly recommended that users use temporary keys when calling the SDK to further enhance security by means of temporary authorization. When applying for temporary keys, please follow the Principle of Least Privilege to prevent leakage of resources beyond the target bucket or objects.
Temporary Keys
Key Callback
Note:
Temporary keys are associated with each COS request.
Temporary keys take precedence over the method for key callback. If both temporary keys and key callback are set, the temporary keys will be used first.
All requests (Request) in the SDK support setting temporary keys via the credential property.
If temporary keys are fully adopted in the project, there is no need to use the method for key callback.
Temporary key ID, Key, and Token can be obtained by referring to Temporary Key Generation and Usage Guidelines.
Objective-C
Swift
// Take a request for uploading files as an example
QCloudCOSXMLUploadObjectRequest* put = [QCloudCOSXMLUploadObjectRequest new];
QCloudCredential * credential = [QCloudCredential new];
// Temporary ID of the Secret Key
credential.secretID = @"secretID";
// Key of the Temporary Secret
credential.secretKey = @"secretKey";
// Token of the Temporary Secret
credential.token = @"token";
// Set temporary keys.
put.credential = credential;
// Local file path
NSURL* url = [NSURL fileURLWithPath:@"file's URL"];
// Bucket name, composed of BucketName-Appid, can be viewed in the COS console at https://console.tencentcloud.com/cos5/bucket.
put.bucket = @"examplebucket-1250000000";
// Object Key is the full path of the object on COS. If including directories, the format is "video/xxx/movie.mp4".
put.object = @"exampleobject";
// The content of the object to be uploaded. You can pass a variable of type NSData* or NSURL*.
put.body = url;
// Monitor upload progress.
[put setSendProcessBlock:^(int64_t bytesSent,
int64_t totalBytesSent,
int64_t totalBytesExpectedToSend) {
// bytesSent Number of bytes to be sent this time (a large file may be sent in multiple times).
// totalBytesSent Bytes sent
// totalBytesExpectedToSend Total bytes expected to be sent in this upload (that is, the file size)
}];

// Monitor upload result.
[put setFinishBlock:^(id outputObject, NSError *error) {
// You can obtain the etag or custom headers from the response in the outputObject.
NSDictionary * result = (NSDictionary *)outputObject;
}];

[[QCloudCOSTransferMangerService defaultCOSTransferManager] UploadObject:put];
// Take a request for uploading files as an example
let put:QCloudCOSXMLUploadObjectRequest = QCloudCOSXMLUploadObjectRequest<AnyObject>();
let credential = QCloudCredential()
// Temporary ID of the Secret Key
credential.secretID = "secretID"
// Key of the Temporary Secret
credential.secretKey = "secretKey"
// Token of the Temporary Secret
credential.token = "token"
// Set temporary keys.
put.credential = credential
// Bucket name, composed of BucketName-Appid, can be viewed in the COS console at https://console.tencentcloud.com/cos5/bucket.
put.bucket = "examplebucket-1250000000";
// Object Key is the full path of the object on COS. If including directories, the format is "video/xxx/movie.mp4".
put.object = "exampleobject";
// The content of the object to be uploaded. You can pass a variable of type NSData* or NSURL*.
put.body = NSURL.fileURL(withPath: "Local File Path") as AnyObject;

// Monitor upload result.
put.setFinish { (result, error) in
// Obtain the upload result
if error != nil{
print(error!);
}else{
print(result!);
}
}

// Monitor upload progress.
put.sendProcessBlock = { (bytesSent, totalBytesSent,
totalBytesExpectedToSend) in
// bytesSent Number of bytes to be sent this time (a large file may be sent in multiple times).
// totalBytesSent Bytes sent
// totalBytesExpectedToSend Total bytes expected to be sent in this upload (that is, the file size)
};
// Set upload parameters.
put.initMultipleUploadFinishBlock = {(multipleUploadInitResult, resumeData) in
// After the initialization of multipart upload is completed, this block will be called back, where you can obtain the resumeData
// and can generate a request for multipart upload using resumeData
let resumeUploadRequest = QCloudCOSXMLUploadObjectRequest<AnyObject>
.init(request: resumeData as Data?);
}

QCloudCOSTransferMangerService.defaultCOSTransferManager().uploadObject(put);


Note:
Key callback supports various key types: temporary keys, permanent keys, and signatures computed by the server.
In certain business scenarios, client requests and access keys may not strictly follow a one-to-one relationship, and multiple requests may share the same key. To reduce integration complexity and the burden of key management for business parties, we provide a key delegation mechanism. Through this mechanism, business parties only need to implement the specified proxy interface (QCloudSignatureProvider). The SDK can then dynamically obtain valid access keys for each network request, significantly streamlining the key invocation and management process.
In addition, to ensure key security, business parties may not directly distribute keys to clients but instead employ security strategies such as signatures for permission control. To address this, the SDK also supports initiating requests with signatures in callbacks, allowing business parties to generate temporary access credentials through secure computation. This ensures the security of keys during transmission and usage while meeting enterprise-level security and compliance requirements.
Client-Side Secret Key Management
Server-Side Signing
Objective-C
Swift
SwiftUI
//AppDelegate.m
//AppDelegate needs to conform to QCloudSignatureProvider
@interface AppDelegate()<QCloudSignatureProvider>
@end

@implementation AppDelegate

- (BOOL)application:(UIApplication * )application
didFinishLaunchingWithOptions:(NSDictionary * )launchOptions {
QCloudServiceConfiguration* configuration = [QCloudServiceConfiguration new];
QCloudCOSXMLEndPoint* endpoint = [[QCloudCOSXMLEndPoint alloc] init];
endpoint.regionName = @"COS_REGION";
endpoint.useHTTPS = true;
configuration.endpoint = endpoint;
// Set delegation of key callback
configuration.signatureProvider = self;
[QCloudCOSXMLService registerDefaultCOSXMLWithConfiguration:configuration];
[QCloudCOSTransferMangerService registerDefaultCOSTransferMangerWithConfiguration:
configuration];
return YES;
}


// Delegate method for key callback
- (void)signatureWithFields:(QCloudSignatureFields*)fileds
request:(QCloudBizHTTPRequest*)request
urlRequest:(NSMutableURLRequest*)urlRequst
compelete:(QCloudHTTPAuthentationContinueBlock)continueBlock
{
/**
* Obtain the secret key here. If using a permanent secret key, it can be ignored.
* ...
*/
/**
* Here, it can be either temporary keys or permanent keys.
* To obtain temporary secret keys, see: https://www.tencentcloud.com/document/product/436/14048
* Note: Permanent keys must not be used in production environments and are intended for debugging purposes only.
*/
QCloudCredential* credential = [QCloudCredential new];
// Secret key SecretId
credential.secretID = @"SECRETID";
// Secret Key SecretKey
credential.secretKey = @"SECRETKEY";
// Token for Secret Key (not required for permanent keys; required for temporary keys)
credential.token = @"TOKEN";
// It is strongly recommended to return the server time as the start time of the signature to avoid invalid signatures caused by significant deviations in the user's device local time (parameters startTime and expiredTime are in seconds).
credential.startDate = [NSDate dateWithTimeIntervalSince1970:startTime]; // Unit is seconds
credential.expirationDate = [NSDate dateWithTimeIntervalSince1970:expiredTime]];// Unit is seconds.
QCloudAuthentationV5Creator* creator = [[QCloudAuthentationV5Creator alloc]
initWithCredential:credential];
// In the SDK, by default, all Headers below are included in the signature and do not need to be set.
// To exclude a specific Header from the signature, remove it from the array below and assign the updated array to shouldSignedList.
// creator.shouldSignedList = @[@"Cache-Control", @"Content-Disposition", @"Content-Encoding", @"Content-Length", @"Content-MD5", @"Content-Type", @"Expect", @"Expires", @"If-Match" , @"If-Modified-Since" , @"If-None-Match" , @"If-Unmodified-Since" , @"Origin" , @"Range" , @"transfer-encoding" ,@"Host",@"Pic-Operations",@"ci-process"];
// Note: Do not perform copy or mutableCopy operations on urlRequst here
QCloudSignature *signature = [creator signatureForData:urlRequst];
continueBlock(signature, nil);
}


@end
//AppDelegate.swift
//AppDelegate needs to conform to QCloudSignatureProvider
class AppDelegate: UIResponder, UIApplicationDelegate,
QCloudSignatureProvider {

func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions:
[UIApplication.LaunchOptionsKey: Any]?) -> Bool {
let config = QCloudServiceConfiguration.init();
let endpoint = QCloudCOSXMLEndPoint.init();
endpoint.regionName = "COS_REGION";
endpoint.useHTTPS = true;
config.endpoint = endpoint;
// Set delegate for key callback
config.signatureProvider = self;
QCloudCOSXMLService.registerDefaultCOSXML(with: config);
QCloudCOSTransferMangerService.registerDefaultCOSTransferManger(
with: config);
return true
}

// Delegate method for key callback
func signature(with fileds: QCloudSignatureFields!,
request: QCloudBizHTTPRequest!,
urlRequest urlRequst: NSMutableURLRequest!,
compelete continueBlock: QCloudHTTPAuthentationContinueBlock!) {
/**
* Obtain the secret key here. If using a permanent secret key, it can be ignored.
* ...
*/
/**
* Here, it can be either temporary keys or permanent keys.
* To obtain temporary secret keys, see: https://www.tencentcloud.com/document/product/436/14048.
* Note: Permanent keys must not be used in production environments and are intended for debugging purposes only.
*/
let credential = QCloudCredential.init();
// SecretId for Secret Key
credential.secretID = "SECRETID";
// SecretKey for Secret Key
credential.secretKey = "SECRETKEY";
// Token for Secret Key (not required for permanent keys; required for temporary keys)
credential.token = "TOKEN";
// It is strongly recommended to return the server time as the start time of the signature to avoid invalid signatures caused by significant deviations in the user's device local time (parameters startTime and expiredTime are in seconds).
credential.startDate = Date.init(timeIntervalSince1970: TimeInterval(startTime)!) DateFormatter().date(from: "startTime");
credential.expirationDate = Date.init(timeIntervalSince1970: TimeInterval(expiredTime)!)
let creator = QCloudAuthentationV5Creator.init(credential: credential);
// Note: Do not perform copy or mutableCopy operations on urlRequst here.
let signature = creator?.signature(forData: urlRequst);
continueBlock(signature,nil);
}
}

import SwiftUI
import QCloudCOSXML

@main
struct SwiftUIDemoApp: App {
init() {
// Call SDK configuration during application initialization.
COSManager.shared.setupCOSSDK();
}
var body: some Scene {
WindowGroup {
ContentView()
}
}
}


// COSManager needs to conform to QCloudSignatureProvider.
class COSManager: NSObject, QCloudSignatureProvider {
static let shared = COSManager()
private override init() {}
func setupCOSSDK() {
let config = QCloudServiceConfiguration.init();
let endpoint = QCloudCOSXMLEndPoint.init();
endpoint.regionName = "COS_REGION";
endpoint.useHTTPS = true;
config.endpoint = endpoint;
config.signatureProvider = self;
QCloudCOSXMLService.registerDefaultCOSXML(with: config);
QCloudCOSTransferMangerService.registerDefaultCOSTransferManger(with: config);
}

// Delegate method for key callback
func signature(with fileds: QCloudSignatureFields!,
request: QCloudBizHTTPRequest!,
urlRequest urlRequst: NSMutableURLRequest!,
compelete continueBlock: QCloudHTTPAuthentationContinueBlock!) {
/**
* Obtain the secret key here. If using a permanent secret key, it can be ignored.
* ...
*/
/**
* Here, it can be either temporary keys or permanent keys.
* To obtain temporary secret keys, see: https://www.tencentcloud.com/document/product/436/14048.
* Note: Permanent keys must not be used in production environments and are intended for debugging purposes only.
*/
let credential = QCloudCredential.init();
// SecretId for Secret Key
credential.secretID = "SECRETID";
// SecretKey for Secret Key
credential.secretKey = "SECRETKEY";
// Token for Secret Key (not required for permanent keys; required for temporary keys)
credential.token = "TOKEN";
// It is strongly recommended to return the server time as the start time of the signature to avoid invalid signatures caused by significant deviations in the user's device local time (parameters startTime and expiredTime are in seconds).
credential.startDate = Date.init(timeIntervalSince1970: TimeInterval(startTime)!) DateFormatter().date(from: "startTime");
credential.expirationDate = Date.init(timeIntervalSince1970: TimeInterval(expiredTime)!)
let creator = QCloudAuthentationV5Creator.init(credential: credential);
// Note: Do not perform copy or mutableCopy operations on urlRequst here.
let signature = creator?.signature(forData: urlRequst);
continueBlock(signature,nil);
}
}
Note:
Additionally, the SDK provides a fence mechanism (QCloudCredentailFenceQueue) where all requests to retrieve signatures wait for signature completion before execution, eliminating the need to manually manage the asynchronous process. Note: The fence mechanism only applies to the key callback method and is only applicable when keys are managed client-side.

The usage of the fence mechanism is as follows:
Objective-C
Swift
SwiftUI

// AppDelegate needs to conform to QCloudCredentailFenceQueueDelegate.
@interface AppDelegate () <QCloudSignatureProvider, QCloudCredentailFenceQueueDelegate>
// The object that controls the fence mechanism
@property (nonatomic, strong) QCloudCredentailFenceQueue *credentialFenceQueue;

@end

@implementation AppDelegate

- (BOOL)application:(UIApplication * )application
didFinishLaunchingWithOptions:(NSDictionary * )launchOptions {
// ... Process related to SDK initialization is omitted here.
self.credentialFenceQueue = [QCloudCredentailFenceQueue new];
// Set the delegate object for the fence mechanism
self.credentialFenceQueue.delegate = self;
return YES;
}

// The delegate for key callback needs to use the fence object to retrieve signatures
- (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);
}
}];
}

// Obtaining the secret key in the callback delegate of the fence mechanism.
- (void)fenceQueue:(QCloudCredentailFenceQueue *)queue requestCreatorWithContinue:(QCloudCredentailFenceQueueContinue)continueBlock {
[[[NSURLSession sharedSession]dataTaskWithURL:[NSURL URLWithString:@"http://******"] completionHandler:^(NSData * _Nullable data, NSURLResponse * _Nullable response, NSError * _Nullable error) {
// Request temporary keys from the interface for business services.
NSDictionary * dic = [NSJSONSerialization JSONObjectWithData:data options:NSJSONReadingTopLevelDictionaryAssumed error:nil];
NSDictionary * credentials = dic[@"credentials"];
QCloudCredential *credential = [QCloudCredential new];
credential.secretID = credentials[@"tmpSecretId"];
credential.secretKey = credentials[@"tmpSecretKey"];;
credential.token = credentials[@"sessionToken"];;
// Expiration time of the signature
credential.expirationDate = nil;
credential.startDate = nil;
QCloudAuthentationV5Creator *creator = [[QCloudAuthentationV5Creator alloc] initWithCredential:credential];
continueBlock(creator, nil);
}] resume];
}

@end

import UIKit
import QCloudCOSXML

@main
class AppDelegate: UIResponder, UIApplicationDelegate, QCloudSignatureProvider, QCloudCredentailFenceQueueDelegate {

var window: UIWindow?
var credentialFenceQueue: QCloudCredentailFenceQueue!
func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions:
[UIApplication.LaunchOptionsKey: Any]?) -> Bool {
// ... Process related to SDK initialization is omitted here.
credentialFenceQueue = QCloudCredentailFenceQueue()
credentialFenceQueue.delegate = self
return true
}
// MARK: - QCloudSignatureProvider
func signature(with fileds: QCloudSignatureFields!,
request: QCloudBizHTTPRequest!,
urlRequest urlRequst: NSMutableURLRequest!,
compelete continueBlock: QCloudHTTPAuthentationContinueBlock!) {
credentialFenceQueue.performAction { (creator: QCloudAuthentationCreator?, error: Error?) in
if let error = error {
continueBlock(nil, error)
} else if let creator = creator {
let signature = creator.signature(for: urlRequst)
continueBlock(signature, nil)
}
}
}

// MARK: - QCloudCredentailFenceQueueDelegate
func fenceQueue(_ queue: QCloudCredentailFenceQueue!, requestCreatorWithContinue continueBlock: QCloudCredentailFenceQueueContinue!) {
// Construct the URL for requesting temporary keys (please replace with your actual server address).
guard let url = URL(string: "http://******") else {
// Handle failure of URL construction
let error = NSError(domain: "AppDelegate", code: -1, userInfo: [NSLocalizedDescriptionKey: "Invalid URL for temporary key"])
continueBlock(nil, error)
return
}
let task = URLSession.shared.dataTask(with: url) { [weak self] (data, response, error) in
// Handle network errors.
if let error = error {
continueBlock(nil, error)
return
}
// Ensure data exists.
guard let data = data else {
let error = NSError(domain: "AppDelegate", code: -2, userInfo: [NSLocalizedDescriptionKey: "No data received from server"])
continueBlock(nil, error)
return
}
do {
// Parse JSON data.
if let json = try JSONSerialization.jsonObject(with: data, options: []) as? [String: Any],
let credentials = json["credentials"] as? [String: Any],
let tmpSecretId = credentials["tmpSecretId"] as? String,
let tmpSecretKey = credentials["tmpSecretKey"] as? String,
let sessionToken = credentials["sessionToken"] as? String {
// Create a QCloudCredential object and set temporary keys.
let credential = QCloudCredential()
credential.secretID = tmpSecretId
credential.secretKey = tmpSecretKey
credential.token = sessionToken
// If the server returns startTime and expiredTime, it is recommended to set them.
// credential.startDate = Date(timeIntervalSince1970: startTime)
// credential.expirationDate = Date(timeIntervalSince1970: expiredTime)
let creator = QCloudAuthentationV5Creator(credential: credential)
continueBlock(creator, nil)
} else {
// JSON parsing failed or key missing.
let error = NSError(domain: "AppDelegate", code: -3, userInfo: [NSLocalizedDescriptionKey: "Failed to parse temporary key response"])
continueBlock(nil, error)
}
} catch {
// JSON parsing exception
continueBlock(nil, error)
}
}
task.resume() // Start the network task.
}
}


import SwiftUI
import QCloudCOSXML

@main
struct SwiftUIDemoApp: App {
init() {
// Call SDK configuration during application initialization.
COSManager.shared.setupCOSSDK();
}
var body: some Scene {
WindowGroup {
ContentView()
}
}
}

class COSManager: NSObject, QCloudSignatureProvider, QCloudCredentailFenceQueueDelegate
{
static let shared = COSManager()
private let credentialFenceQueue = QCloudCredentailFenceQueue()
private override init() {}
func setupCOSSDK() {
// ... SDK initialization process omitted for brevity
credentialFenceQueue.delegate = self
}
// MARK: - QCloudSignatureProvider
func signature(with fileds: QCloudSignatureFields!,
request: QCloudBizHTTPRequest!,
urlRequest urlRequst: NSMutableURLRequest!,
compelete continueBlock: QCloudHTTPAuthentationContinueBlock!) {
credentialFenceQueue.performAction { (creator: QCloudAuthentationCreator?, error: Error?) in
if let error = error {
continueBlock(nil, error)
} else if let creator = creator {
let signature = creator.signature(for: urlRequst)
continueBlock(signature, nil)
}
}
}


// MARK: - QCloudCredentailFenceQueueDelegate
func fenceQueue(_ queue: QCloudCredentailFenceQueue!, requestCreatorWithContinue continueBlock: QCloudCredentailFenceQueueContinue!) {
// Construct the URL for requesting temporary keys (please replace with your actual server address).
guard let url = URL(string: "http://******") else {
// Handle failure of URL construction
let error = NSError(domain: "AppDelegate", code: -1, userInfo: [NSLocalizedDescriptionKey: "Invalid URL for temporary key"])
continueBlock(nil, error)
return
}
let task = URLSession.shared.dataTask(with: url) { [weak self] (data, response, error) in
// Handle network errors.
if let error = error {
continueBlock(nil, error)
return
}
// Ensure data exists.
guard let data = data else {
let error = NSError(domain: "AppDelegate", code: -2, userInfo: [NSLocalizedDescriptionKey: "No data received from server"])
continueBlock(nil, error)
return
}
do {
// Parse JSON data.
if let json = try JSONSerialization.jsonObject(with: data, options: []) as? [String: Any],
let credentials = json["credentials"] as? [String: Any],
let tmpSecretId = credentials["tmpSecretId"] as? String,
let tmpSecretKey = credentials["tmpSecretKey"] as? String,
let sessionToken = credentials["sessionToken"] as? String {
// Create a QCloudCredential object and set temporary keys.
let credential = QCloudCredential()
credential.secretID = tmpSecretId
credential.secretKey = tmpSecretKey
credential.token = sessionToken
// If the server returns startTime and expiredTime, it is recommended to set them.
// credential.startDate = Date(timeIntervalSince1970: startTime)
// credential.expirationDate = Date(timeIntervalSince1970: expiredTime)
let creator = QCloudAuthentationV5Creator(credential: credential)
continueBlock(creator, nil)
} else {
// JSON parsing failed or key missing.
let error = NSError(domain: "AppDelegate", code: -3, userInfo: [NSLocalizedDescriptionKey: "Failed to parse temporary key response"])
continueBlock(nil, error)
}
} catch {
// JSON parsing exception
continueBlock(nil, error)
}
}
task.resume() // Start the network task.
}
}


Objective-C
Swift
SwiftUI
//AppDelegate.m
//AppDelegate needs to conform to QCloudSignatureProvider
@interface AppDelegate()<QCloudSignatureProvider>
@end

@implementation AppDelegate

- (BOOL)application:(UIApplication * )application
didFinishLaunchingWithOptions:(NSDictionary * )launchOptions {

QCloudServiceConfiguration* configuration = [QCloudServiceConfiguration new];
QCloudCOSXMLEndPoint* endpoint = [[QCloudCOSXMLEndPoint alloc] init];

// Replace with the user's region. The region to which the created bucket belongs can be viewed in the console at https://console.tencentcloud.com/cos5/bucket.
// For a list of all regions supported by COS, see https://www.qcloud.com/document/product/436/6224.
endpoint.regionName = @"COS_REGION";
// Use HTTPS.
endpoint.useHTTPS = true;
configuration.endpoint = endpoint;
// The provider of the secret key is self
configuration.signatureProvider = self;
// Initialize an Example of COS Service
[QCloudCOSXMLService registerDefaultCOSXMLWithConfiguration:configuration];
[QCloudCOSTransferMangerService registerDefaultCOSTransferMangerWithConfiguration:
configuration];
return YES;
}

- (void)signatureWithFields:(QCloudSignatureFields*)fileds
request:(QCloudBizHTTPRequest*)request
urlRequest:(NSMutableURLRequest*)urlRequst
compelete:(QCloudHTTPAuthentationContinueBlock)continueBlock
{
// Time of signature expiration
NSDate *expiration = [[[NSDateFormatter alloc] init]
dateFromString:@"expiredTime"];
QCloudSignature *signature = [[QCloudSignature alloc] initWithSignature:
@"signature calculated in the background" expiration:expiration];
signature.token = @"Temporary Key Token";// Permanent Key does not need Token.
continueBlock(signature, nil);
}
@end
//AppDelegate.swift
//AppDelegate needs to conform to QCloudSignatureProvider

class AppDelegate: UIResponder, UIApplicationDelegate,
QCloudSignatureProvider {

func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions:
[UIApplication.LaunchOptionsKey: Any]?) -> Bool {
let config = QCloudServiceConfiguration.init();

let endpoint = QCloudCOSXMLEndPoint.init();

// Replace with the user's region. The region to which the created bucket belongs can be viewed in the console at https://console.tencentcloud.com/cos5/bucket.
// For a list of all regions supported by COS, see https://www.qcloud.com/document/product/436/6224.
endpoint.regionName = "COS_REGION";
// Use HTTPS.
endpoint.useHTTPS = true;
config.endpoint = endpoint;
// The provider of the secret key is self
config.signatureProvider = self;

// Initialize an Example of COS Service
QCloudCOSXMLService.registerDefaultCOSXML(with: config);
QCloudCOSTransferMangerService.registerDefaultCOSTransferManger(
with: config);
return true
}
func signature(with fileds: QCloudSignatureFields!,
request: QCloudBizHTTPRequest!,
urlRequest urlRequst: NSMutableURLRequest!,
compelete continueBlock: QCloudHTTPAuthentationContinueBlock!) {
// Time of signature expiration
let expiration = DateFormatter().date(from: "expiredTime");
let signature = QCloudSignature.init(signature: "signature calculated in the backend",
expiration: expiration);
signature.token = "Temporary Key Token";// Permanent Key does not need Token.
continueBlock(signature,nil);
}
}

import SwiftUI
import QCloudCOSXML

@main
struct SwiftUIDemoApp: App {
init() {
// Call SDK configuration during application initialization.
COSManager.shared.setupCOSSDK();
}
var body: some Scene {
WindowGroup {
ContentView()
}
}
}

class COSManager: NSObject, QCloudSignatureProvider {
static let shared = COSManager()
private override init() {}
func setupCOSSDK() {
let config = QCloudServiceConfiguration.init();
let endpoint = QCloudCOSXMLEndPoint.init();
// Replace with the user's region. The region to which the created bucket belongs can be viewed in the console at https://console.tencentcloud.com/cos5/bucket.
// For a list of all regions supported by COS, see https://www.qcloud.com/document/product/436/6224.
endpoint.regionName = "COS_REGION";
// Use HTTPS.
endpoint.useHTTPS = true;
config.endpoint = endpoint;
config.signatureProvider = self;
// Initialize an Example of COS Service
QCloudCOSXMLService.registerDefaultCOSXML(with: config);
QCloudCOSTransferMangerService.registerDefaultCOSTransferManger(with: config);
}

// The entry point for obtaining the signature. This demonstrates the process of acquiring a temporary key and calculating the signature.
// You can also customize the process of calculating the signature.
func signature(with fileds: QCloudSignatureFields!,
request: QCloudBizHTTPRequest!,
urlRequest urlRequst: NSMutableURLRequest!,
compelete continueBlock: QCloudHTTPAuthentationContinueBlock!) {
// Time of signature expiration
let expiration = DateFormatter().date(from: "expiredTime");
let signature = QCloudSignature.init(signature: "signature calculated in the backend",
expiration: expiration);
signature.token = "Token of the Temporary Key";// Permanent Key does not need Token
continueBlock(signature,nil);
}
}

Configure Domain Name

The SDK supports accessing COS services via custom domains.
Usage: During the step of "Initialize the COS service", pass in the specified domain when instantiating QCloudCOSXMLEndPoint.
Note:
If custom domains for the origin or Global Accelerate domains do not need to be specified in your business scenario, skip this step.
Business parties can learn about custom domains for the origin and Global Accelerate domains via Domain Name Management Overview and Global Accelerate Overview.
It is recommended to use custom domains for the origin or Global Accelerate domains. Domains for CDN acceleration are not recommended. CDN acceleration domains are primarily optimized for download acceleration and are not suitable for scenarios of upload acceleration. Using domains for CDN acceleration will yield no acceleration effect.
Objective-C
Swift
NSString *customDomain = @"exampledomain.com"; // Custom domain for the origin or Global Accelerate domain
QCloudCOSXMLEndPoint *endpoint = [[QCloudCOSXMLEndPoint alloc] initWithLiteralURL:[NSURL URLWithString:customDomain]];
QCloudServiceConfiguration* configuration = [QCloudServiceConfiguration new];
// Replace with the user's region. The host region of created buckets can be viewed in the console: https://console.tencentcloud.com/cos5/bucket.
// For a list of all regions supported by COS, see https://www.qcloud.com/document/product/436/6224.
// Use HTTPS.
endpoint.regionName = @"COS_REGION";
endpoint.useHTTPS = true;
configuration.endpoint = endpoint;
// Initialize a sample of the COS service
[QCloudCOSXMLService registerDefaultCOSXMLWithConfiguration:configuration];
[QCloudCOSTransferMangerService registerDefaultCOSTransferMangerWithConfiguration:
configuration];
let endpoint = QCloudCOSXMLEndPoint.init(literalURL: NSURL.init(string: "exampledomain.com") as URL?);
let config = QCloudServiceConfiguration.init();
// Replace with the user's region. The host region of created buckets can be viewed in the console: https://console.tencentcloud.com/cos5/bucket.
// For a list of all regions supported by COS, see https://www.qcloud.com/document/product/436/6224.
// Use HTTPS.
endpoint.useHTTPS = true;
endpoint.regionName = "COS_REGION";
config.endpoint = endpoint;

// Initialize a sample of the COS service
QCloudCOSXMLService.registerDefaultCOSXML(with: config);
QCloudCOSTransferMangerService.registerDefaultCOSTransferManger(
with: config);


Configure Concurrency (Optional)

The SDK supports customizing the number of concurrent requests.
Usage: During the "Initialize the COS service" step, customize the number of concurrent requests and the auto-incrementing upper limit for the number of concurrent requests.
Note:
The SDK internally processes requests via multi-threaded concurrency. The default number of concurrencies is 1, which dynamically adjusts based on real-time network speed, with a minimum of 1 and a maximum of 4.
Objective-C
Swift
// Set concurrency count to 4.
[QCloudHTTPSessionManager shareClient].customConcurrentCount = 4;
// Set automatic upper limit to 8.
[QCloudHTTPSessionManager shareClient].maxConcurrencyTask = 8;
// Set concurrency number to 4
QCloudHTTPSessionManager.shareClient.customConcurrentCount = 4;
// Set automatic upper limit to 8.
QCloudHTTPSessionManager.shareClient.maxConcurrencyTask = 8;

Access the COS Service

Using file upload/download as an example, this demonstrates how to access the relevant services of the SDK.
File Upload
Downloading Files
The SDK supports uploading local files and binary data (NSData). The following uses uploading local files as an example.
Objective-C
Swift
QCloudCOSXMLUploadObjectRequest* put = [QCloudCOSXMLUploadObjectRequest new];
// Local file path
NSURL* url = [NSURL fileURLWithPath:@"URL of the file"];
// Bucket name, composed of BucketName-Appid, can be viewed in the COS console at https://console.tencentcloud.com/cos5/bucket.
put.bucket = @"examplebucket-1250000000";
// Object Key is the full path of the object on COS. If including directories, the format is "video/xxx/movie.mp4".
put.object = @"exampleobject";
// The content of the object to be uploaded. You can pass a variable of type NSData* or NSURL*.
put.body = url;
// Monitor upload progress.
[put setSendProcessBlock:^(int64_t bytesSent,
int64_t totalBytesSent,
int64_t totalBytesExpectedToSend) {
// bytesSent Number of bytes to be sent this time (a large file may be sent in multiple times).
// totalBytesSent Bytes sent
// totalBytesExpectedToSend Total bytes expected to be sent in this upload (that is, the file size)
}];

// Monitor upload result.
[put setFinishBlock:^(id outputObject, NSError *error) {
// You can obtain the etag or custom headers from the response in the outputObject.
NSDictionary * result = (NSDictionary *)outputObject;
}];

[[QCloudCOSTransferMangerService defaultCOSTransferManager] UploadObject:put];
let put:QCloudCOSXMLUploadObjectRequest = QCloudCOSXMLUploadObjectRequest<AnyObject>();
// Bucket name, composed of BucketName-Appid, can be viewed in the COS console at https://console.tencentcloud.com/cos5/bucket.
put.bucket = "examplebucket-1250000000";
// Object Key is the full path of the object on COS. If including directories, the format is "video/xxx/movie.mp4".
put.object = "exampleobject";
// The content of the object to be uploaded. You can pass a variable of type NSData* or NSURL*.
put.body = NSURL.fileURL(withPath: "Local File Path") as AnyObject;

// Monitor upload result.
put.setFinish { (result, error) in
// Obtain the upload result
if error != nil{
print(error!);
}else{
print(result!);
}
}

// Monitor upload progress.
put.sendProcessBlock = { (bytesSent, totalBytesSent,
totalBytesExpectedToSend) in
// bytesSent Number of bytes to be sent this time (a large file may be sent in multiple times).
// totalBytesSent Bytes sent
// totalBytesExpectedToSend Total bytes expected to be sent in this upload (that is, the file size)
};
// Set upload parameters.
put.initMultipleUploadFinishBlock = {(multipleUploadInitResult, resumeData) in
// After the initialization of multipart upload is completed, this block will be called back, where you can obtain the resumeData
// and can generate a request for multipart upload using resumeData
let resumeUploadRequest = QCloudCOSXMLUploadObjectRequest<AnyObject>
.init(request: resumeData as Data?);
}

QCloudCOSTransferMangerService.defaultCOSTransferManager().uploadObject(put);

Objective-C
Swift
QCloudCOSXMLDownloadObjectRequest * request = [QCloudCOSXMLDownloadObjectRequest new];

// Bucket name, composed of BucketName-Appid, can be viewed in the COS console at https://console.tencentcloud.com/cos5/bucket.
request.bucket = @"examplebucket-1250000000";
// Object Key is the full path of the object on COS. If including directories, the format is "video/xxx/movie.mp4".
request.object = @"exampleobject";

//Set the URL for the download path. If the path is set, the file will be downloaded to the specified path
request.downloadingURL = [NSURL fileURLWithPath:@"Local File Path"];

// Monitor download results.
[request setFinishBlock:^(id outputObject, NSError *error) {
// outputObject contains all the HTTP response headers
NSDictionary* info = (NSDictionary *) outputObject;
}];

// Monitor download progress.
[request setDownProcessBlock:^(int64_t bytesDownload,
int64_t totalBytesDownload,
int64_t totalBytesExpectedToDownload) {
// bytesDownload Number of bytes to be downloaded this time (a large file may be transmitted in multiple parts)
// totalBytesDownload Number of bytes downloaded
// totalBytesExpectedToDownload Total number of bytes expected to be downloaded (that is, the file size).
}];

[[QCloudCOSTransferMangerService defaultCOSTransferManager] DownloadObject:request];
let request : QCloudCOSXMLDownloadObjectRequest = QCloudCOSXMLDownloadObjectRequest();

// Bucket name, composed of BucketName-Appid, can be viewed in the COS console at https://console.tencentcloud.com/cos5/bucket.
request.bucket = "examplebucket-1250000000";
// Object Key
request.object = "exampleobject";

//Set the URL for the download path. If the path is set, the file will be downloaded to the specified path
request.downloadingURL = NSURL.fileURL(withPath: "Local File Path") as URL?;

// Monitor download progress.
request.downProcessBlock = { (bytesDownload, totalBytesDownload,
totalBytesExpectedToDownload) in
// bytesDownload Number of bytes to be downloaded this time (a large file may be transmitted in multiple parts).
// totalBytesDownload Number of bytes downloaded
// totalBytesExpectedToDownload Total number of bytes expected to be downloaded (that is, the file size).
}

// Monitor download results.
request.finishBlock = { (copyResult, error) in
if error != nil{
print(error!);
}else{
print(copyResult!);
}
}

QCloudCOSTransferMangerService.defaultCOSTransferManager().downloadObject(request);

Note:
For more complete examples, please visit GitHub.
After uploading, you can generate a file download URL using the same Key. For specific usage, please see the Generate Pre-signed URL documentation. Note, however, that if your file has private read permissions, the download URL will only be valid for a limited time.

FAQs

If you encounter errors such as functions or methods not existing when using the XML version SDK, please first upgrade the XML version SDK to the latest version and then retry.
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback