1# EmbeddedUIExtensionAbility
2
3## Overview
4
5[EmbeddedUIExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md) is an [ExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-extensionAbility.md) component of the EMBEDDED_UI type. It provides the capability of embedded UIs across processes.
6
7The EmbeddedUIExtensionAbility must be used together with the [EmbeddedComponent](../reference/apis-arkui/arkui-ts/ts-container-embedded-component.md). Specifically, with the EmbeddedComponent, you can embed the UI provided by the EmbeddedUIExtensionAbility into a [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) of the same application. The EmbeddedUIExtensionAbility runs in a process independent of the UIAbility for UI layout and rendering. It is usually used in modular development scenarios where process isolation is required.
8
9> **NOTE**
10>
11> Currently, the EmbeddedUIExtensionAbility and **EmbeddedComponent** are supported only on devices configured with multiple processes.
12>
13> The **EmbeddedComponent** can be used only in the UIAbility, and the EmbeddedUIExtensionAbility to start must belong to the same application as the UIAbility.<!--Del-->
14> The EmbeddedUIExtensionAbility supports the multiton pattern and inherits the process model of the UIExtensionAbility. For details about the multiton pattern and process configuration of the UIExtensionAbility, see [UIExtensionAbility](uiextensionability.md).<!--DelEnd-->
15
16The EmbeddedUIExtensionAbility provides related capabilities through the [UIExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-uiExtensionContext.md) and [UIExtensionContentSession](../reference/apis-ability-kit/js-apis-app-ability-uiExtensionContentSession.md). In this document, the started EmbeddedUIExtensionAbility is called the provider, and the EmbeddedComponent that starts the EmbeddedUIExtensionAbility is called the client.
17
18## Developing the EmbeddedUIExtensionAbility Provider
19
20### Lifecycle
21
22The [EmbeddedUIExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md) class provides the lifecycle callbacks [onCreate](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md#embeddeduiextensionabilityoncreate), [onSessionCreate](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md#embeddeduiextensionabilityonsessioncreate), [onSessionDestroy](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md#embeddeduiextensionabilityonsessiondestroy), [onForeground](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md#embeddeduiextensionabilityonforeground), [onBackground](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md#embeddeduiextensionabilityonbackground), and [onDestroy](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md#embeddeduiextensionabilityondestroy). You must override them as required.
23
24- **onCreate**: called to initialize the service logic when an EmbeddedUIExtensionAbility is created.
25- **onSessionCreate**: called when a **UIExtensionContentSession** instance is created for the EmbeddedUIExtensionAbility.
26- **onSessionDestroy**: called when a **UIExtensionContentSession** instance is destroyed for the EmbeddedUIExtensionAbility.
27- **onForeground**: called when the EmbeddedUIExtensionAbility is switched from the background to the foreground.
28- **onBackground**: called when the EmbeddedUIExtensionAbility is switched from the foreground to the background.
29- **onDestroy**: called to clear resources when the EmbeddedUIExtensionAbility is destroyed.
30
31### How to Develop
32
33To implement a provider, create an [EmbeddedUIExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md) in DevEco Studio as follows:
34
351. In the **ets** directory of a module in the project, right-click and choose **New > Directory** to create a directory named **EmbeddedUIExtAbility**.
36
372. Right-click the **EmbeddedUIExtAbility** directory, and choose **New > File** to create a file named **EmbeddedUIExtAbility.ets**.
38
393. Open the **EmbeddedUIExtAbility.ets** file and import its dependencies. Customize a class that inherits from **EmbeddedUIExtensionAbility** and implement the lifecycle callbacks [onCreate](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md#embeddeduiextensionabilityoncreate), [onSessionCreate](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md#embeddeduiextensionabilityonsessioncreate), [onSessionDestroy](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md#embeddeduiextensionabilityonsessiondestroy), [onForeground](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md#embeddeduiextensionabilityonforeground), [onBackground](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md#embeddeduiextensionabilityonbackground), and [onDestroy](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md#embeddeduiextensionabilityondestroy).
40
41    ```ts
42    import { EmbeddedUIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit';
43
44    const TAG: string = '[ExampleEmbeddedAbility]'
45
46    export default class ExampleEmbeddedAbility extends EmbeddedUIExtensionAbility {
47      onCreate() {
48        console.log(TAG, `onCreate`);
49      }
50
51      onForeground() {
52        console.log(TAG, `onForeground`);
53      }
54
55      onBackground() {
56        console.log(TAG, `onBackground`);
57      }
58
59      onDestroy() {
60        console.log(TAG, `onDestroy`);
61      }
62
63      onSessionCreate(want: Want, session: UIExtensionContentSession) {
64        console.log(TAG, `onSessionCreate, want: ${JSON.stringify(want)}`);
65        let param: Record<string, UIExtensionContentSession> = {
66          'session': session
67        };
68        let storage: LocalStorage = new LocalStorage(param);
69        session.loadContent('pages/extension', storage);
70      }
71
72      onSessionDestroy(session: UIExtensionContentSession) {
73        console.log(TAG, `onSessionDestroy`);
74      }
75    }
76    ```
77
784. Write the entry page file **pages/Index.ets**, which will be loaded in [onSessionDestroy](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md#embeddeduiextensionabilityonsessiondestroy) of the EmbeddedUIExtensionAbility.
79
80    ```ts
81    import { UIExtensionContentSession } from '@kit.AbilityKit';
82    
83    let storage = LocalStorage.getShared()
84    
85    @Entry(storage)
86    @Component
87    struct Extension {
88      @State message: string = 'EmbeddedUIExtensionAbility Index';
89      private session: UIExtensionContentSession | undefined = storage.get<UIExtensionContentSession>('session');
90    
91      build() {
92        Column() {
93          Text(this.message)
94            .fontSize(20)
95            .fontWeight(FontWeight.Bold)
96          Button("terminateSelfWithResult").fontSize(20).onClick(() => {
97            this.session?.terminateSelfWithResult({
98              resultCode: 1,
99              want: {
100                bundleName: "com.example.embeddeddemo",
101                abilityName: "ExampleEmbeddedAbility",
102              }});
103          })
104        }.width('100%').height('100%')
105      }
106    }
107    ```
108
1095. Register the EmbeddedUIExtensionAbility in the [module.json5 file](../quick-start/module-configuration-file.md) of the module in the project. Set **type** to **embeddedUI** and **srcEntry** to the code path of the EmbeddedUIExtensionAbility.
110
111    ```json
112    {
113      "module": {
114        "extensionAbilities": [
115          {
116            "name": "EmbeddedUIExtAbility",
117            "icon": "$media:icon",
118            "description": "EmbeddedUIExtAbility",
119            "type": "embeddedUI",
120            "srcEntry": "./ets/EmbeddedUIExtAbility/EmbeddedUIExtAbility.ets"
121          },
122        ]
123      }
124    }
125    ```
126
127
128
129## Developing the EmbeddedUIExtensionAbility Client
130
131You can load the [EmbeddedUIExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-embeddedUIExtensionAbility.md) in the application through the [EmbeddedComponent](../reference/apis-arkui/arkui-ts/ts-container-embedded-component.md) on the [UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md) page. Two fields are added to [want](../reference/apis-ability-kit/js-apis-app-ability-want.md).parameters for the EmbeddedUIExtensionAbility: **ohos.extension.processMode.hostSpecified** and **ohos.extension.processMode.hostInstance**.
132- **ohos.extension.processMode.hostSpecified** specifies the name of the process in which the EmbeddedUIExtensionAbility that is not started for the first time runs. If this field is not configured, the EmbeddedUIExtensionAbility runs in the same process as the [UIExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-uiExtensionAbility.md). Example configuration: "ohos.extension.processMode.hostSpecified": "com.ohos.inentexecutedemo:share." 
133- **ohos.extension.processMode.hostInstance** specifies whether to start the EmbeddedUIExtensionAbility as an independent process. If **false** is passed in, the EmbeddedUIExtensionAbility is started based on the UIExtensionAbility process model. If **true** is passed in, a process is created, regardless of the process model configured for the UIExtensionAbility. Example configuration: "ohos.extension.processMode.hostInstance": "true".
134
135If both fields are configured, **ohos.extension.processMode.hostSpecified** takes precedence, meaning that the EmbeddedUIExtensionAbility runs in the specified process.
136For example, add the following content to the home page file **pages/Index.ets**:
137```ts
138import { Want } from '@kit.AbilityKit';
139import { BusinessError } from '@kit.BasicServicesKit';
140
141@Entry
142@Component
143struct Index {
144  @State message: string = 'Message: '
145  private want: Want = {
146    bundleName: "com.example.embeddeddemo",
147    abilityName: "EmbeddedUIExtAbility",
148    parameters: {
149      'ohos.extension.processMode.hostInstance': 'true'
150    }
151  }
152
153  build() {
154    Row() {
155      Column() {
156        Text(this.message).fontSize(30)
157        EmbeddedComponent(this.want, EmbeddedType.EMBEDDED_UI_EXTENSION)
158          .width('100%')
159          .height('90%')
160          .onTerminated((info: TerminationInfo) => {
161            this.message = 'Terminarion: code = ' + info.code + ', want = ' + JSON.stringify(info.want);
162          })
163          .onError((error: BusinessError) => {
164            this.message = 'Error: code = ' + error.code;
165          })
166      }
167      .width('100%')
168    }
169    .height('100%')
170  }
171}
172```
173