• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Subscribing to Common Events in Static Mode (for System Applications Only)
2
3## When to Use
4
5A static subscriber is started once it receives a target event published by the system or application. At the same time, the [onReceiveEvent()](../reference/apis/js-apis-application-staticSubscriberExtensionAbility.md#staticsubscriberextensionabilityonreceiveevent) callback is triggered.
6
7You can implement the service logic in the [onReceiveEvent()](../reference/apis/js-apis-application-staticSubscriberExtensionAbility.md#staticsubscriberextensionabilityonreceiveevent) callback. For example, if an application needs to execute some initialization tasks during device power-on, the application can subscribe to the power-on event in static mode. After receiving the power-on event, the application is started to execute the initialization tasks.
8
9Subscribing to a common event in static mode is achieved by configuring a declaration file and implementing a class that inherits from [StaticSubscriberExtensionAbility](../reference/apis/js-apis-application-staticSubscriberExtensionAbility.md).
10
11> **NOTE**
12>
13> The static subscription mode has negative impact on system power consumption. Therefore, exercise caution when using this mode.
14
15## How to Develop
16
171. Declaring a static subscriber.
18
19   To declare a static subscriber, create an ExtensionAbility, which is derived from the **StaticSubscriberExtensionAbility** class, in the project.
20
21   You can implement service logic in the **onReceiveEvent()** callback.
22
23   ```ts
24   import StaticSubscriberExtensionAbility from '@ohos.application.StaticSubscriberExtensionAbility'
25
26   export default class StaticSubscriber extends StaticSubscriberExtensionAbility {
27     onReceiveEvent(event) {
28       console.info('onReceiveEvent, event: ' + event.event);
29     }
30   }
31   ```
32
332. Configure static subscriber settings.
34
35   After writing the static subscriber code, configure the subscriber in the [module.json5](../quick-start/module-configuration-file.md) file.
36
37   ```ts
38   {
39     "module": {
40       ...
41       "extensionAbilities": [
42         {
43           "name": "StaticSubscriber",
44           "srcEntry": "./ets/staticsubscriber/StaticSubscriber.ts",
45           "description": "$string:StaticSubscriber_desc",
46           "icon": "$media:icon",
47           "label": "$string:StaticSubscriber_label",
48           "type": "staticSubscriber",
49           "exported": true,
50           "metadata": [
51             {
52               "name": "ohos.extension.staticSubscriber",
53               "resource": "$profile:subscribe"
54             }
55           ]
56         }
57       ]
58       ...
59     }
60   }
61   ```
62
63   Some fields in the file are described as follows:
64
65   - **srcEntry **: entry file path of the ExtensionAbility, that is, the file path of the static subscriber declared in Step 2.
66
67   - **type**: ExtensionAbility type. For a static subscriber, set this field to **staticSubscriber**.
68
69   - **metadata**: level-2 configuration file information of the ExtensionAbility. The configuration information varies according to the ExtensionAbility type. Therefore, you must use different config files to indicate the specific configuration.
70        - **name**: name of the ExtensionAbility. For a static subscriber, declare the name as **ohos.extension.staticSubscriber** for successful identification.
71        - **resource**: path that stores the ExtensionAbility configuration, which is customizable. In this example, the path is **resources/base/profile/subscribe.json**.
72
73
743. Configure the level-2 configuration file to which the metadata points.
75
76   ```json
77   {
78     "commonEvents": [
79       {
80         "name": "xxx",
81         "permission": "xxx",
82         "events":[
83           "xxx"
84         ]
85       }
86     ]
87   }
88   ```
89
90   If the level-2 configuration file is not declared in this format, the file cannot be identified. Some fields in the file are described as follows:
91
92   - **name**: name of the ExtensionAbility, which must be the same as the name of **extensionAbility** declared in **module.json5**.
93   - **permission**: permission required for the publisher. If a publisher without the required permission attempts to publish an event, the event is regarded as invalid and will not be published.
94   - **events**: list of target events to subscribe to.
95
964. Modify the [preset configuration file](https://gitee.com/openharmony/vendor_hihope/blob/master/rk3568/preinstall-config/install_list_permissions.json) of the device, that is, the **/system/etc/app/install_list_permission.json** file on the device. When the device is started, this file is read. During application installation, the common event type specified by **allowCommonEvent** in the file is authorized. The **install_list_permission.json** file contains the following fields:
97
98   - **bundleName**: bundle name of the application.
99   - **app_signature**: fingerprint information of the application. For details, see [Application Privilege Configuration Guide](../../device-dev/subsystems/subsys-app-privilege-config-guide.md#configuration-in-install_list_capabilityjson).
100   - **allowCommonEvent**: type of common event that can be started by static broadcast.
101
102   > **NOTE**
103   >
104   > The **install_list_permissions.json** file is available only for preinstalled applications.
105
106   ```json
107   [
108     ...
109     {
110       "bundleName": "com.example.myapplication", // Bundle name of the application.
111       "app_signature": ["****"], // Fingerprint information of the application.
112       "allowCommonEvent": ["usual.event.A", "usual.event.B"], // Type of common event that can be started by static broadcast.
113       ]
114     }
115   ]
116   ```
117
118<!--no_check-->