1# 接入安全隐私框架
2
3安全隐私接入框架允许两种接入方式：ExtensionAbility和UIAbility方式接入。
4
5应用接入后，将按照bundleName的字母顺序在隐私中心展示。
6
7业务接入方需在本应用模块下的module.json5配置文件中配置相应的action和metadata，供安全隐私中心菜单接入框架扫描、解析。
8
9开发者可参考以下步骤，完成对安全隐私框架的接入。
10
11## 新增元数据资源配置文件
12
13业务接入方需要新增一个元数据资源配置json文件，用于承载接入安全隐私框架的方式、跳转的Ability等内容，具体字段说明如表所示：
14
15| key值（属性名称） | value值                                                      | 是否必填 | 说明                                              |
16| ----------------- | ------------------------------------------------------------ | -------- | ------------------------------------------------- |
17| displayedMode     | - list：代表列表方式接入。<br />- card：代表卡片方式接入，当前版本暂不支持。 | 是       | 目前仅支持列表展示，输入card/list均按照列表展示。 |
18| mainTitleResource | 入口菜单显示的主标题字串的资源名                             | 是       | -                                                 |
19| dstAbilityMode    | - 0： 表示被拉起的ability为UIAbility。<br />- 1： 表示被拉起的ability为UIExtensionAbility。 | 是       | -                                                 |
20| dstAbilityName    | 跳转的目标Ability。<br />- 当dstAbilityMode为0时，该ability为UIAbility。<br />- 当dstAbilityMode为1时，该ability需继承自UIExtensionAbility，接入方在此ability中加载自身页面。 | 是       | -                                                 |
21| dstBundleName     | 跳转的目的bundle名称。                                         | 是       | -                                                 |
22| displayUserConfig | - ONLY_PRIMARY_USER：仅主用户展示。<br />- ONLY_SUB_USER：仅子用户展示。 | 否       | 如果不填，默认为向所有用户展示。                  |
23
24本文档中以新建一个security_privacy.json文件为例，来指导业务接入方完成配置，实际的json文件的名称可由开发者自定义。
25
26此文件需放置在对应模块的`"resource/rawfile/xxx.json"`中。
27
28```json
29{
30  "displayedMode": "list",
31  "mainTitleResource": "$string:main_title",
32  "dstAbilityMode": 0,
33  "dstAbilityName": "EntryAbility",
34  "dstBundleName": "com.example.test"
35}
36```
37
38## 修改应用配置文件
39
40各模块的module.json5配置文件中，承载了该模块UIAbility组件和ExtensionAbility组件的描述信息、应用运行过程中所需的权限等信息。接入安全隐私框架需将一下相关字段配置到module.json5中。
41
42### 配置action
43
44在module.json5文件的“ skill ”标签中，配置隐私中心的action值`"action.access.privacy.center"`。
45
46```typescript
47"skills": [
48  {
49    "actions": [
50      "action.access.privacy.center"
51    ]
52  }
53]
54```
55
56### 配置metadata
57
58在module.json5文件的“ metadata ”标签中，新增“ name ”为“ metadata.access.privacy.center ”、“ value ”为元数据json文件名称的条目。
59
60元数据json文件即为上一步新增的`"resource/rawfile/xxx.json"`。
61
62> **说明：**
63>
64> 开发者需要根据dstAbilityMode来选择action、metadata的配置。
65>
66> - 如果被拉起的页面是UIAbility，则需配置到“ abilities ”中，
67>
68> - 如果是UIExtensionAbility，则需配置到“ extensionAbilities ” 中。
69>
70>   **在配置extensionAbilities时，其中type类型需配置成"sys/commonUI"。**
71
72当前示例仅提供接入安全隐私框架涉及的标签用法，module.json5中的其余标签字段，需要开发者根据实际情况填写。
73
74```typescript
75// UIAbility方式接入
76"abilities": [
77  {
78    "skills": [
79      {
80        "actions": [
81          "action.access.privacy.center"
82        ]
83      }
84    ],
85    "metadata": [
86      {
87        "name": 'metadata.access.privacy.center',
88        "value": 'security_privacy.json'
89      }
90    ]
91  }
92]
93```
94
95```typescript
96// ExtensionAbility方式接入
97"extensionAbilities": [
98      {
99        "type": "sys/commonUI",
100        "skills": [
101          {
102            "actions": [
103              "action.access.privacy.center"
104            ]
105          }
106        ],
107        "metadata": [
108          {
109            "name": 'metadata.access.privacy.center',
110            "value": 'security_privacy.json'
111          }
112        ]
113      }
114    ]
115```
116
117### 配置权限
118
119业务接入方需申请权限[ohos.permission.ACCESS_SECURITY_PRIVACY_CENTER](../AccessToken/permissions-for-system-apps.md#ohospermissionaccess_security_privacy_center)，来确保应用可以接入框架菜单。
120
121申请方式请参考[访问控制开发指导](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/security/AccessToken/determine-application-mode.md)。
122
123## 配置Ability页面（以UIAbility方式接入）
124
125如果为UIAbility方式接入，则不需要单独做相关的配置，直接使用默认生成的方式。
126
127示例：
128
129```typescript
130import AbilityConstant from '@ohos.app.ability.AbilityConstant';
131import hilog from '@ohos.hilog';
132import UIAbility from '@ohos.app.ability.UIAbility';
133import Want from '@ohos.app.ability.Want';
134import window from '@ohos.window';
135
136export default class EntryAbility extends UIAbility {
137  onWindowStageCreate(windowStage: window.WindowStage): void {
138    // Main window is created, set main page for this ability
139    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
140    windowStage.loadContent('pages/Index', (err, data) => {
141      if (err.code) {
142        hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
143        return;
144      }
145      hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
146    });
147  }
148}
149```
150
151## 配置Ability页面（以ExtensionAbility方式接入）
152
153如果为ExtensionAbility方式接入，Ability页面需继承自ExtensionAbility，并且需修改相应配置，使用session的方式来拉起接入应用的主页面。
154
155示例：
156
157```typescript
158import hilog from '@ohos.hilog';
159import Want from '@ohos.app.ability.Want';
160import ExtensionAbility from '@ohos.app.ability.ExtensionAbility';
161import UIExtensionContentSession from '@ohos.app.ability.UIExtensionContentSession';
162
163export default class EntryAbility extends ExtensionAbility {
164  onSessionCreate(want: Want, session: UIExtensionContentSession) {
165    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onSessionCreate');
166    let param: Record<string, Object> = {
167      'session': session
168    }
169    let storage: LocalStorage = new LocalStorage(param)
170    session.loadContent('pages/Index', storage)
171  }
172}
173```
174
175## 接入页面退出（以UIAbility方式接入）
176
177如果是UIAbility的方式接入，接入方需主动退出时，例如页面有返回按钮，想要销毁应用的页面时，可以直接调用router.back()或者terminateSelf()来销毁当前页面。
178
179示例：
180
181```typescript
182import router from '@ohos.router';
183
184@Entry()
185@Component
186struct Index {
187
188  build() {
189    Row() {
190      Column() {
191        Button("click to back")
192          .onClick(() => {
193            router.back()
194          })
195      }
196      .width('100%')
197    }
198    .height('100%')
199  }
200}
201```
202
203## 接入页面退出（以ExtensionAbility方式接入）
204
205如果是UIExtensionAbility的方式接入，接入方需主动退出时，例如页面有返回按钮，想要销毁应用的页面时，可以通过UIExtensionContentSession的sendData向使用方发送数据 `{“action”: "exit"}`，使用方接收到消息之后将退出拉起的页面。
206
207示例：
208
209```typescript
210import UIExtensionContentSession from '@ohos.app.ability.UIExtensionContentSession'
211
212let storage = LocalStorage.getShared()
213
214@Entry(storage)
215@Component
216struct Index {
217  private session: UIExtensionContentSession = storage.get<UIExtensionContentSession>('session') as UIExtensionContentSession
218  build() {
219    Row() {
220      Column() {
221        Button("click to back")
222          .onClick(() => {
223            this.session.sendData({ 'action': "exit" })
224          })
225      }
226      .width('100%')
227    }
228    .height('100%')
229  }
230}
231```
232