1# Sharing Configurations Between Applications (ArkTS) 2 3## When to Use 4 5Sharing configurations between applications allows you to manage common configuration information in a centralized manner, thereby improving collaboration efficiency. 6 7This feature is supported since API version 20. 8 9## Working Principles 10 11The working principles of configuration sharing between applications are as follows: 12 131. **Configuration publisher (data provider)**: provides default shared configuration items and dynamically modifies them. Currently, the following configuration modes are supported: 14 - **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. 15 - **Dynamic configuration**: configuration items can be dynamically added, deleted, or modified via related APIs, without depending on application upgrade. 162. **Configuration accessor (data consumer)**: calls APIs to obtain configuration information or subscribe to/unsubscribe from a listening for configuration changes. 17 18## Constraints 19 20An application can publish a maximum of 32 configuration items, including static and dynamic ones. 21 22## Available APIs 23The following table lists the APIs used to share configurations between applications. 24 25### Public APIs 26 27| Name | Description | 28| ------------------------------- | ------------------------------------------------------------------------------------------------------ | 29| createDataProxyHandle(): Promise<DataProxyHandle> | Creates a data proxy operation handle, which is used to subscribe to, publish, and obtain configurations.| 30 31### APIs for Configuration Publishers 32 33| Name | Description | 34| ------------------------------------------------------------ | ------------------ | 35| publish(data: ProxyData[], config: DataProxyConfig): Promise<DataProxyResult[]> | Publishes or modifies configuration items.| 36| delete(uris: string[], config: DataProxyConfig): Promise<DataProxyResult[]> | Deletes configuration items. | 37 38### APIs for Configuration Accessors 39 40| Name | Description | 41| ------------------------------------------------------------ | -------------------- | 42| get(uris: string[], config: DataProxyConfig): Promise<DataProxyGetResult[]> | Obtains configuration items. | 43| on(event: 'dataChange', uris: string[], config: DataProxyConfig, callback: AsyncCallback<DataProxyChangeInfo[]>): DataProxyResult[] | Subscribes to configuration item changes. | 44| off(event: 'dataChange', uris: string[], config: DataProxyConfig, callback?: AsyncCallback<DataProxyChangeInfo[]>): DataProxyResult[] | Unsubscribes from configuration item changes.| 45 46 47## Configuring the Publisher 48### Configuration in module.json5 49Store the the **shared_config.json** file in the **resources/base/profile** directory and reference it by using the **$** symbol in the **crossAppSharedConfig** field of the **module.json5** file. The **shared_config.json** file defines the configuration items that can be shared between applications. 50 51 52```json 53"module":{ 54 "crossAppSharedConfig": "$profile:shared_config.json" 55 } 56``` 57 58 59The **shared_config.json** file contains the following configuration items: 60 61- **uri**: fixed at the format of **"datashareproxy://{*bundleName*}/{*path*}"**, in which **bundleName** indicates the bundle name of the publisher application, and **path** can be set to any value but must be unique in the same application. The maximum length is 256 bytes. 62 63- **value**: value of the configuration item, with a maximum length of 4096 bytes. 64 65- **allowList**: [appIdentifiers](../reference/apis-ability-kit/js-apis-bundleManager.md#signatureinfo) list of applications that are allowed to access the configuration. A maximum of 256 **appIdentifiers** are supported. You can use the [getBundleInfoForSelf](../reference/apis-ability-kit/js-apis-bundleManager.md#bundlemanagergetbundleinfoforself) API to obtain the **appIdentifier** of an application. 66 67- An application can publish a maximum of 32 configuration items, including static and dynamic ones. 68```json 69{ 70 "crossAppSharedConfig": [ 71 { 72 "uri": "datashareproxy://com.example.example/key1", 73 "value": "xxx", 74 "allowList": ["xxx", "xxx"] 75 }, 76 { 77 "uri": "datashareproxy://com.example.example/key2", 78 "value": "xxx", 79 "allowList": ["xxx", "xxx"] 80 } 81 ] 82} 83``` 84 85### Static Configuration 86 87Static 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. 88 89### Dynamic Configuration 90 91You can call the **publish** or **delete** API to manage configuration items as follows: 92 93- Call the **publish** API to publish or modify configuration items. 94 95 ```ts 96 import { dataShare } from '@kit.ArkData'; 97 import { BusinessError } from '@kit.BasicServicesKit'; 98 99 export function publish() { 100 dataShare.createDataProxyHandle().then((dsProxyHelper) => { 101 const newConfigData: dataShare.ProxyData[] = [{ 102 uri: 'datashareproxy://com.example.app1/config1', 103 value: 'Value1', 104 allowList: ['com.example.app2', 'com.example.app3'], 105 }, { 106 uri: 'datashareproxy://com.example.app1/config2', 107 value: 'Value2', 108 allowList: ['com.example.app3', 'com.example.app4'], 109 },]; 110 const config: dataShare.DataProxyConfig = { 111 type: dataShare.DataProxyType.SHARED_CONFIG, 112 }; 113 dsProxyHelper.publish(newConfigData, config).then((results: dataShare.DataProxyResult[]) => { 114 results.forEach((result) => { 115 console.info(`URI: ${result.uri}, Result: ${result.result}`); 116 }); 117 }).catch((error: BusinessError) => { 118 console.error('Error publishing config:', error); 119 }); 120 }).catch((error: BusinessError) => { 121 console.error('Error creating DataProxyHandle:', error); 122 }); 123 } 124 ``` 125 126- Call the **delete** API to delete the configuration items. 127 128 ```ts 129 import { dataShare } from '@kit.ArkData'; 130 import { BusinessError } from '@kit.BasicServicesKit'; 131 132 export function deleteShareConfig() { 133 dataShare.createDataProxyHandle().then((dsProxyHelper) => { 134 const urisToDelete: string[] = 135 ['datashareproxy://com.example.app1/config1', 'datashareproxy://com.example.app1/config2',]; 136 const config: dataShare.DataProxyConfig = { 137 type: dataShare.DataProxyType.SHARED_CONFIG, 138 }; 139 dsProxyHelper.delete(urisToDelete, config).then((results: dataShare.DataProxyResult[]) => { 140 results.forEach((result) => { 141 console.info(`URI: ${result.uri}, Result: ${result.result}`); 142 }); 143 }).catch((error: BusinessError) => { 144 console.error('Error deleting config:', error); 145 }); 146 }).catch((error: BusinessError) => { 147 console.error('Error creating DataProxyHandle:', error); 148 }); 149 } 150 ``` 151 152## Configuring the Accessor 153 154You can call the **get**, **on**, or **off** API to perform operations as follows: 155 156### Obtaining Configuration Items 157 158Call the **get** API to obtain the configuration information. 159 160```ts 161import { dataShare } from '@kit.ArkData'; 162import { BusinessError } from '@kit.BasicServicesKit'; 163 164export function get() { 165 dataShare.createDataProxyHandle().then((dsProxyHelper) => { 166 const urisToGet: string[] = 167 ['datashareproxy://com.example.app1/config1', 'datashareproxy://com.example.app1/config2',]; 168 const config: dataShare.DataProxyConfig = { 169 type: dataShare.DataProxyType.SHARED_CONFIG, 170 }; 171 dsProxyHelper.get(urisToGet, config).then((results: dataShare.DataProxyGetResult[]) => { 172 results.forEach((result) => { 173 console.info(`URI: ${result.uri}, Result: ${result.result}, AllowList: ${result.allowList}`); 174 }); 175 }).catch((error: BusinessError) => { 176 console.error('Error getting config:', error); 177 }); 178 }).catch((error: BusinessError) => { 179 console.error('Error creating DataProxyHandle:', error); 180 }); 181} 182``` 183 184### Subscribing to/Unsubscribing from Configuration Changes 185 186Call the **on** API to subscribe to configuration changes or the **off** API to unsubscribe from the configuration changes. 187 188```ts 189import { dataShare } from '@kit.ArkData'; 190import { BusinessError } from '@kit.BasicServicesKit'; 191 192export function watchConfigChanges() { 193 dataShare.createDataProxyHandle().then((dsProxyHelper) => { 194 const uris: string[] = 195 ['datashareproxy://com.example.app1/config1', 'datashareproxy://com.example.app1/config2',]; 196 const config: dataShare.DataProxyConfig = { 197 type: dataShare.DataProxyType.SHARED_CONFIG, 198 }; 199 const callback = (err: BusinessError<void>, changes: dataShare.DataProxyChangeInfo[]): void => { 200 if (err) { 201 console.error('err:', err); 202 } else { 203 changes.forEach((change) => { 204 console.info(`Change Type: ${change.type}, URI: ${change.uri}, Value: ${change.value}`); 205 }); 206 } 207 }; 208 // Subscribe to configuration changes. 209 const listenResults: dataShare.DataProxyResult[] = dsProxyHelper.on('dataChange', uris, config, callback); 210 listenResults.forEach((result) => { 211 console.info(`URI: ${result.uri}, Result: ${result.result}`); 212 }); 213 // Unsubscribe from configuration changes. 214 const unListenResults: dataShare.DataProxyResult[] = dsProxyHelper.off('dataChange', uris, config, callback); 215 unListenResults.forEach((result) => { 216 console.info(`URI: ${result.uri}, Result: ${result.result}`); 217 }); 218 }).catch((error: BusinessError) => { 219 console.error('Error creating DataProxyHandle:', error); 220 }); 221} 222``` 223