HarmonyOS5-Cloud-Storage-SDK-Guide-EN

A Guide to Integrating Huawei Cloud Storage SDK in HarmonyOS ArkTS Applications

Hello everyone! Today, let's talk about how to integrate the Huawei Cloud Storage SDK into a HarmonyOS application based on ArkTS (API 9-11). This guide will walk you through the entire process, from setting up the environment to implementing the code, and will also provide helpful tips for common issues you might encounter along the way.

1. Prerequisites

1.1 Development Environment Requirements

Development Tool: HUAWEI DevEco Studio 3.1+ (the latest version is recommended)
SDK Version:
- Compile SDK Version ≥ 9
- Compatible SDK Version ≥ 9
Project Structure: Must use the Stage model (remember to check this option when creating a new project)

📢 Tip: If you are migrating from an old project, remember to confirm that apiType is set to stageMode in build-profile.json5.

1.2 Obtaining the Configuration File

Log in to the HUAWEI Developers console.
Go to Project settings > Cloud development > Cloud Storage
Download the agconnect-services.json file.
Check if the file contains the following key configurations:

"cloudstorage": {
    "default_storage": "your-default-storage-bucket-name", 
    "storage_url": "https://agc-storage-drcn.platform.dbankcloud.cn"
}

⚠️ Important: If default_storage is not configured, initialization will fail!

2. Full Project Configuration Process

2.1 Placing the Configuration File

Create the following directory in your project: entry/src/main/resources/rawfile
Drag the downloaded agconnect-services.json into this directory.

2.2 Adding SDK Dependencies

Open the oh-package.json5 file and add:

"dependencies": {
    "@hw-agconnect/hmcore": "^1.0.1",
    "@hw-agconnect/cloud": "^1.0.1"
}

Execute the sync command (or click Sync Now in the IDE):

cd entry
ohpm install

3. Step-by-Step Code Implementation

3.1 SDK Initialization

Add the following to EntryAbility.ets:

import { initialize } from '@hw-agconnect/hmcore';
import util from '@ohos/util';

// Initialize in the onCreate lifecycle
async onCreate() {
    // Read the configuration file
    const input = await this.context.resourceManager.getRawFileContent('agconnect-services.json');
    const jsonString = new util.TextDecoder().decodeWithStream(input);

    // Perform initialization
    initialize(this.context, JSON.parse(jsonString));
}

3.2 Adding Network Permissions

Add the following to module.json5:

"requestPermissions": [
    {
        "name": "ohos.permission.INTERNET"
    }
]

🔐 If you need to access local storage, you also need to dynamically request permissions like ohos.permission.READ_MEDIA.

4. Advanced Configuration (Optional)

4.1 Manually Configuring Keys

If the configuration file does not contain the keys, you can add them via code:

import { setApiKey, setClientSecret } from '@hw-agconnect/hmcore';

// Add after initialize
setApiKey("Your API Key");
setClientSecret("Your Client Secret");

4.2 Configuring Multiple Storage Instances

After creating multiple storage buckets in the cloud console, you can access them by specifying the instance name:

const storage = cloud.storage("your-other-storage-instance-name");

5. Quick Verification Tip

After completing the integration, you can try uploading a test file:

// Get the default storage instance
const storage = cloud.storage();

// Create a file reference
const fileRef = storage.ref('test/hello.txt');

// Upload text content
fileRef.putString('Hello HarmonyOS!').then(() => {
    console.log('Upload successful!');
});

Check if the test/hello.txt file appears in the Cloud Storage management console~

6. Common Issues Troubleshooting Guide

Initialization Fails:
- Check if the path to agconnect-services.json is correct.
- Confirm that the default_storage value matches the one in the console.
- Check for missing network permissions.
Dependency Conflicts:
- Try running ohpm update to update dependency versions.
- Check the version numbers in oh-package-lock.json.
On-Device Debugging Issues:
- Ensure the device is logged in with a HUAWEI ID for developers.
- Check if the signing certificate matches the configuration in the console.

We hope this guide helps you successfully integrate the Huawei Cloud Storage service! If you encounter any problems during implementation, feel free to leave a comment for discussion. We also welcome you to share your integration experience to help strengthen the HarmonyOS ecosystem together.

Finally, don't forget to give the article a like ❤️. Your support is our greatest motivation to continue creating high-quality tutorials! See you next time~