This topic describes how to get started with the iOS SDK.

For more information, see the following examples and cases of this project:

You can also directly run the git clone command and configure the following parameters:

Run the project demo as follows:


The following code shows you how to upload and download files on the iOS and Mac platforms.

  • iOS platform
    1. Add the reference.
      #import <AliyunOSSiOS/OSSService.h>
    2. Initialize the OSSClient instance.

      To initialize an OSSClient instance, you must configure the Endpoint field, authentication mode, and Client parameters. Three authentication modes are available: plaintext setting, self-signed, and STS authentication. For more information about how to use the STS authentication mode and learn about the basic knowledge of RAM, see Authorized access. The following code assumes that you have activated RAM and have basic knowledge of it, such as how to obtain the AccessKey ID, AccessKey Secret, and role ID of a RAM user.

      Set AccessKeyId,SecretKeyId, and RoleArn parameters, as shown in Script files. You can use the Python SDK to start a local HTTP service. Use the client code to access the local service and obtain the StsToken.AccessKeyId, StsToken.SecretKeyId, and StsToken.SecurityToken field values.

      For more information, see the "STS instructions" section in the sample.

      NSString *endpoint = "";
      // We recommend that you use STS to initialize the OSSClient instance if you use the mobile device. For more information, see the "STS instructions" section in the sample, as shown in
      id<OSSCredentialProvider> credential = [[OSSStsTokenCredentialProvider alloc] initWithAccessKeyId:@"AccessKeyId" secretKeyId:@"AccessKeySecret" securityToken:@"SecurityToken"];
      client = [[OSSClient alloc] initWithEndpoint:endpoint credentialProvider:credential];

      The use of the OSSClient instance to initiate upload and download requests is thread-safe. You can run multiple tasks concurrently.

    3. Upload a file.

      Assume that you have created a bucket in the console. An OSSTask is returned for each SDK-relevant operation. You can configure a continuation for the task to be completed asynchronously or call waitUntilFinished to wait for the task to be complete.

      OSSPutObjectRequest * put = [OSSPutObjectRequest new];
      put.bucketName = @"<bucketName>";
      put.objectKey = @"<objectKey>";
      put.uploadingData = <NSData *>; // Directly upload NSData.
      put.uploadProgress = ^(int64_t bytesSent, int64_t totalByteSent, int64_t totalBytesExpectedToSend) {
          NSLog(@"%lld, %lld, %lld", bytesSent, totalByteSent, totalBytesExpectedToSend);
      OSSTask * putTask = [client putObject:put];
      [putTask continueWithBlock:^id(OSSTask *task) {
          if (! task.error) {
              NSLog(@"upload object success!") ;
          } else {
              NSLog(@"upload object failed, error: %@" , task.error);
          return nil;
      // Wait until the task is complete.
      // [putTask waitUntilFinished];
    4. Download the specified object.

      Use the following code to download the specified object as NSData:

      OSSGetObjectRequest * request = [OSSGetObjectRequest new];
      request.bucketName = @"<bucketName>";
      request.objectKey = @"<objectKey>";
      request.downloadProgress = ^(int64_t bytesWritten, int64_t totalBytesWritten, int64_t totalBytesExpectedToWrite) {
          NSLog(@"%lld, %lld, %lld", bytesWritten, totalBytesWritten, totalBytesExpectedToWrite);
      OSSTask * getTask = [client getObject:request];
      [getTask continueWithBlock:^id(OSSTask *task) {
          if (! task.error) {
              NSLog(@"download object success!") ;
              OSSGetObjectResult * getResult = task.result;
              NSLog(@"download result: %@", getResult.downloadedData);
          } else {
              NSLog(@"download object failed, error: %@" ,task.error);
          return nil;
      // Wait until the task is complete.
      // [task waitUntilFinished];
  • MAC platform

    Aside from the import method, all operations on the MAC platform are the same as those on the iOS platform.

    import <AliyunOSSOSX/AliyunOSSiOS.h>