SDK Integration

This topic describes how to integrate with MiniApp SDK into your HarmonyOS project. This helps you build a Smart Life miniapp and run it on your smart app.

Preparation

Finish the following operations on the Tuya Developer Platform before you integrate MiniApp SDK into your project:

• Register a developer account, create a product, define data points (DPs), and continue with subsequent steps.
• Create an app based on SmartLife App SDK and get the key information that is required to activate the SDK. For more information, see Preparation.

Prerequisites

The SmartLife App SDK is integrated into your project. For more information, see Fast Integration with SmartLife App SDK for HarmonyOS.

Import SDK

To import the SDK, configure your dependencies. Perform the following steps:

1. Configure the Tuya OHPM environment

   Edit the .ohpmrc file in the project root directory and add the Tuya OHPM source:

   registry=https://ohpm.openharmony.cn/ohpm/
   strict_ssl=false
   publish_registry=https://ohpm-repo.tuya.com/repos/ohpm
   fetch_timeout=60000
   max_concurrent=50
   retry_times=1
   retry_interval=1000
   publish_id=9BA32537EE
   
   # Tuya OHPM source
   @thingsmart:registry=https://ohpm-repo.tuya.com/repos/ohpm
   @rnoh:registry=https://ohpm-repo.tuya.com/repos/ohpm
   @tuya-oh:registry=https://ohpm-repo.tuya.com/repos/ohpm
   
   # Authentication information
   //ohpm-repo.tuya.com/repos/ohpm/:_auth="your_auth_token"
   

2. Configure the plugin

   The plugin can be installed from npmjs or use a local file. Add the following to the oh-package.json5 file in the project root directory:

   {
     "devDependencies": {
       // Method 1: Install from npmjs (recommended)
       "@tuya-client/thing-hmbom-plugin": "^0.0.2",
       // Method 2: Use local file (put the plugin package in the plugins/ directory, refer to Demo)
       // "@tuya-harmony/thingHMBOMPlugin": "file:./plugins/tuya-harmony-thingHMBOMPlugin-1.0.0.tgz"
     }
   }
   

   Configure in the hvigorfile.ts file in the project root directory:

   import { thingBOMPlugin } from '@tuya-harmony/thingHMBOMPlugin';
   import { appTasks } from '@ohos/hvigor-ohos-plugin';
   
   export default {
       system: appTasks,
       plugins: [
           thingBOMPlugin()
       ]
   }
   

3. Pin business package versions

   sdk-requirements.json is a required file and must be placed in the project directory (e.g., entry/sdk-requirements.json). The plugin will install dependencies based on the version information in this file.

   Edit entry/sdk-requirements.json to specify the required business package versions:

   {
     "tag": "feature/publish",
     "versions": {
       "@thingsmart/userlib": "1.1.18",
       "@thingsmart/channel": "1.1.62",
       "@thingsmart/theme": "1.1.4",
       // ... other business packages
     }
   }
   

   For more business package version information, refer to the entry/sdk-requirements.json file in the sample project.

4. Configure business components

   In the module directory where you need to use the corresponding functionality (e.g., entry/), edit the thing-biz-components.json file and add the business components used by your project:

   {
     "components": {
       "@thingsmart/userlib": "1.1.18",
       "@thingsmart/dynamicinitializer": "0.9.2",
       "@thingsmart/dynamicreflect": "0.8.0",
       "@thingsmart/channel": "1.1.62",
       "@thingsmart/theme": "1.1.4",
       "@thingsmart/homelib": "1.0.5",
       "@thingsmart/scenelib": "1.1.0",
       "@thingsmart/messagelib": "1.1.3",
       "@thingsmart/thinglogmodule": "1.0.5",
       "@thingsmart/activatorlib": "1.1.1",
       "@thingsmart/activator": "1.1.14",
       "@thingsmart/device": "1.1.73",
       "@thingsmart/godzillapage": "1.5.8",
       "@thingsmart/thingrouter": "1.0.0",
       "@thingsmart/launchpipeline": "1.0.4",
       "@thingsmart/tunibasekit": "3.29.5",
       "@thingsmart/tuniminikit": "1.0.47",
       "@thingsmart/tunidevicekit": "1.1.4",
       "@thingsmart/tunibizkit": "1.0.38",
       "@thingsmart/tuniipckit": "1.2.30",
       "@thingsmart/tunimediakit": "1.1.1",
       "@thingsmart/tunihomekit": "1.0.11",
       "@thingsmart/mapkit": "1.0.17",
       "@thingsmart/thingpanelmodule": "1.0.28"
     }
   }
   

5. SDK initialization

   // Dynamic reflection initialization
   thingDynamicReflect.init(getReflectMetaInfo(`${bundleName}/${moduleName}`));
   
   // Router initialization
   ThingRouter.initialize()
   ThingRouter.getServiceMgr().setServiceModuleMap(servicesModuleMap());
   
   // Theme initialization
   ThingTheme.getInstance().init(this.context)
   
   // Initialization tasks
   const initMetaInfo = thingDynamicReflect.filterMetaInfo(ThingInitializer.DEFAULT_GROUP);
   new ThingInitializer(initMetaInfo).execute(this.context);
   
   // Page launch pipeline
   AppLaunchPipeliner.getInstance().loadPipelineInfo()
   

   For a complete initialization code example, refer to the entry/src/main/ets/app/AppAbilityStage.ets file in the sample project.

Open miniapp

Use ThingRouter to open miniapp and panel:

import { ThingRouter } from "@thingsmart/thingrouter";

// Open miniapp
ThingRouter.getInstance()
  .setParam({
    // Miniapp URL, format: godzilla://miniprogramId/pagePath?queryA=a
    'url': 'godzilla://miniprogramId/pagePath'  
  })
  .push("miniApp")

// Open device panel
ThingRouter.getInstance()
  .setParam({
    'devId': 'deviceId',  // Device ID
    'groupId': 'groupId',  // Device group ID (optional)
    /**
     * Passed through to initialProps and contextProps
     */
    // 'propsData': {} as Record<string, Object>  // Custom parameters (optional)
  })
  .push("panel")

Import capability package

To expand the possibilities of your miniapp, Tuya encapsulates commonly used capabilities into different capability packages. You can integrate the desired capability package into your project to access the included API resources and thus easily implement the respective business functionality.

Add the corresponding capability package configuration in the entry/thing-biz-components.json file:

{
  "components": {
    "@thingsmart/tunibasekit": "3.29.5",
    "@thingsmart/tunibizkit": "1.0.38",
    "@thingsmart/tunihomekit": "1.0.11",
    "@thingsmart/tunidevicekit": "1.1.4",
    "@thingsmart/mapkit": "1.0.17",
    "@thingsmart/tunimediakit": "1.1.1",
    "@thingsmart/tuniipckit": "1.2.30"
  }
}

For more information, visit the tuya-bizbundle-harmony-sdk-sample GitHub project.