Sharing Configurations Between Applications (ArkTS)

When to Use

Sharing configurations between applications allows you to manage common configuration information in a centralized manner, thereby improving collaboration efficiency.

This feature is supported since API version 20.

Working Principles

The working principles of configuration sharing between applications are as follows:

1. Configuration publisher (data provider): provides default shared configuration items and dynamically modifies them. Currently, the following configuration modes are supported:
   • Static configuration: default shared configuration items are provided when the application package is installed. The configuration takes effect immediately without depending on the application startup.
   • Dynamic configuration: configuration items can be dynamically added, deleted, or modified via related APIs, without depending on application upgrade.
2. Configuration accessor (data consumer): calls APIs to obtain configuration information or subscribe to/unsubscribe from a listening for configuration changes.

Constraints

An application can publish a maximum of 32 configuration items, including static and dynamic ones.

Available APIs

The following table lists the APIs used to share configurations between applications. For details about the APIs, see dataShare.createDataProxyHandle.

Public APIs

APIs for Configuration Publishers

APIs for Configuration Accessors

Configuring the Publisher

Configuration in module.json5

Reference the shared_config.json file by configuring the crossAppSharedConfig field in the module.json5 file. The shared_config.json file defines the configuration items that can be shared between applications. You should store the file in the resources/base/profile directory of the project and reference it using the $ symbol.

{
  "module":{
    "crossAppSharedConfig": "$profile:shared_config"
  }
}

The name of the shared_config.json file can be customized. The root node crossAppSharedConfig is an object array and indicates the number of shared configuration items. An application can publish a maximum of 32 configuration items, including static and dynamic ones. If the number of static configuration items exceeds 32, only the first 32 items that meet the following configuration requirements are parsed, and other configuration items do not take effect.

The following table describes the parameters in the crossAppSharedConfig field.

{
    "crossAppSharedConfig": [
        {
            "uri": "datashareproxy://com.example.example/key1",
            "value": "SHARED_CONFIG_DEMO1",
            "allowList": ["6917573629901742292"]
        },
        {
            "uri": "datashareproxy://com.example.example/key2",
            "value": "SHARED_CONFIG_DEMO2",
            "allowList": ["6917573298752100864", "6917573298752100864"]
        }
    ]
}

Static Configuration

Static configuration refers to the default shared configuration items provided during application installation. These predefined configuration items can take effect regardless of whether the application is started.

Dynamic Configuration

You can call the publish or delete API to manage configuration items as follows:

• Call the publish API to publish or modify configuration items.

  function publishSharedConfig() {
    dataShare.createDataProxyHandle().then((dataProxyHandle) => {
      const newConfigData: dataShare.ProxyData[] = [
        {
          uri: 'datashareproxy://com.samples.shareconfig/config1',
          value: 'Value1',
          allowList: [
            'appIdentifier1',
            'appIdentifier2'
          ]
        },
        {
          uri: 'datashareproxy://com.samples.shareconfig/config2',
          value: 'Value2',
          allowList: [
            'appIdentifier3',
            'appIdentifier4'
          ]
        }
      ];
      const config: dataShare.DataProxyConfig = {
        type: dataShare.DataProxyType.SHARED_CONFIG,
      };
      dataProxyHandle.publish(newConfigData, config).then((results: dataShare.DataProxyResult[]) => {
        results.forEach((result) => {
          console.info(`URI: ${result.uri}, Result: ${result.result}`);
        });
      }).catch((error: BusinessError) => {
        console.error('Error publishing config:', error);
      });
    }).catch((error: BusinessError) => {
      console.error('Error creating DataProxyHandle:', error);
    });
  }
  

  Index.ets

• Call the delete API to delete the configuration items.

  function deleteSharedConfig() {
    dataShare.createDataProxyHandle().then((dataProxyHandle) => {
      const urisToDelete: string[] = [
        'datashareproxy://com.samples.shareconfig/config1',
        'datashareproxy://com.samples.shareconfig/config2'
      ];
      const config: dataShare.DataProxyConfig = {
        type: dataShare.DataProxyType.SHARED_CONFIG,
      };
      dataProxyHandle.delete(urisToDelete, config).then((results: dataShare.DataProxyResult[]) => {
        results.forEach((result) => {
          console.info(`URI: ${result.uri}, Result: ${result.result}`);
        });
      }).catch((error: BusinessError) => {
        console.error('Error deleting config:', error);
      });
    }).catch((error: BusinessError) => {
      console.error('Error creating DataProxyHandle:', error);
    });
  }
  

  Index.ets

Configuring the Accessor

You can call the get, on, or off API to perform operations as follows:

Obtaining Configuration Items

Call the get API to obtain the configuration information.

function getSharedConfig() {
  dataShare.createDataProxyHandle().then((dataProxyHandle) => {
    const urisToGet: string[] = [
      'datashareproxy://com.samples.shareconfig/config1',
      'datashareproxy://com.samples.shareconfig/config2'
    ];
    const config: dataShare.DataProxyConfig = {
      type: dataShare.DataProxyType.SHARED_CONFIG,
    };
    dataProxyHandle.get(urisToGet, config).then((results: dataShare.DataProxyGetResult[]) => {
      results.forEach((result) => {
        console.info(`URI: ${result.uri}, Result: ${result.result}, AllowList: ${result.allowList}`);
      });
    }).catch((error: BusinessError) => {
      console.error('Error getting config:', error);
    });
  }).catch((error: BusinessError) => {
    console.error('Error creating DataProxyHandle:', error);
  });
}

Subscribing to/Unsubscribing from Configuration Changes

Call the on API to subscribe to configuration changes or the off API to unsubscribe from the configuration changes.

function watchConfigChanges() {
  dataShare.createDataProxyHandle().then((dsProxyHelper) => {
    const uris: string[] = [
      'datashareproxy://com.samples.shareconfig/config1',
      'datashareproxy://com.samples.shareconfig/config2'
    ];
    const config: dataShare.DataProxyConfig = {
      type: dataShare.DataProxyType.SHARED_CONFIG,
    };
    const callback = (err: BusinessError<void>, changes: dataShare.DataProxyChangeInfo[]): void => {
      if (err) {
        console.error('err:', err);
      } else {
        changes.forEach((change) => {
          console.info(`Change Type: ${change.type}, URI: ${change.uri}, Value: ${change.value}`);
        });
      }
    };
    // Subscribe to configuration changes.
    const listenResults: dataShare.DataProxyResult[] = dsProxyHelper.on('dataChange', uris, config, callback);
    listenResults.forEach((result) => {
      console.info(`URI: ${result.uri}, Result: ${result.result}`);
    });
    // Unsubscribe from configuration changes.
    const unListenResults: dataShare.DataProxyResult[] = dsProxyHelper.off('dataChange', uris, config, callback);
    unListenResults.forEach((result) => {
      console.info(`URI: ${result.uri}, Result: ${result.result}`);
    });
  }).catch((error: BusinessError) => {
    console.error('Error creating DataProxyHandle:', error);
  });
}