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 or unsubscribe from configuration change notifications.

Constraints

Before API version 26.0.0, an application can publish up to 32 configuration items. Starting from API version 26.0.0, the limit is increased to 64 configuration items per application. This limit applies to the combined total of static and dynamic configuration items.

Available APIs

The following APIs are provided for inter-application configuration sharing. For detailed descriptions of these APIs, see DataProxyHandle.

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 file name shared_config of the shared configuration file shared_config.json is customizable. The root node, crossAppSharedConfig, is an array of objects that defines the shared configuration items.
Before API version 26.0.0, an application can publish up to 32 configuration items. This limit applies to the combined total of static and dynamic configuration items. If more than 32 static configuration items are defined, only the first 32 items that comply with the crossAppSharedConfig configuration requirements are parsed. The remaining items are ignored.
Starting from API version 26.0.0, an application can publish up to 64 configuration items. This limit applies to the combined total of static and dynamic configuration items. If more than 64 static configuration items are defined, only the first 64 items that comply with the crossAppSharedConfig configuration requirements are parsed. The remaining items are ignored.

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"]
        },
        {
            "uri": "datashareproxy://com.example.example/key3",
            "value": "ALLOW ALL APP READ",
            "allowList": ["all"]
        }
    ]
}

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);
  });
}