1# Cross-Device Migration (for System Applications Only) 2 3 4## When to Use 5 6The main task of cross-device migration is to migrate the current task (including the page control status) of an application to the target device so that the task can continue on it. Cross-device migration supports the following functionalities: 7 8- Storage and restoration of custom data 9 10- Storage and restoration of page routing information and page control status data 11 12- Application compatibility detection 13 14 15## Cross-Device Migration Process 16 17The following figure shows the cross-device migration process. 18 19**Figure 1** Cross-device migration process 20 21 22 23## Constraints 24 25- Since cross-device migration task management is not available, you can only develop applications that support cross-device migration. Your application cannot initiate migration. 26 27- Cross-device migration can be performed between the same UIAbility component. In other words, the components must have the same **bundleName**, **abilityName**, and **signature**. 28 29 30## Best Practices 31 32For better user experience, you are advised to use the **wantParam** parameter to transmit data smaller than 100 KB. 33 34 35## Available APIs 36 37The table below describes the main APIs used for cross-device migration. For details, see [API Reference](../reference/apis/js-apis-app-ability-uiAbility.md). 38 39**Table 1** Cross-device migration APIs 40 41| **API**| Description| 42| -------- | -------- | 43| onContinue(wantParam : {[key: string]: any}): OnContinueResult | Called by the initiator to store the data required for migration and indicate whether the migration is accepted.<br>- **AGREE**: The migration is accepted.<br>- **REJECT**: The migration is rejected.<br>- **MISMATCH**: The version does not match.| 44| onCreate(want: Want, param: AbilityConstant.LaunchParam): void; | Called by the target to restore the data and UI page in the multi-instance migration scenario.| 45| onNewWant(want: Want, launchParams: AbilityConstant.LaunchParam): void; | Called by the target to restore the data and UI page in the singleton migration scenario.| 46 47 48## How to Develop 49 501. Request the **ohos.permission.DISTRIBUTED_DATASYNC** permission. For details, see [Declaring Permissions in the Configuration File](../security/accesstoken-guidelines.md#declaring-permissions-in-the-configuration-file). 51 522. Display a dialog box to ask authorization from the user when the application is started for the first time. For details, see [Requesting User Authorization](../security/accesstoken-guidelines.md#requesting-user-authorization). 53 543. Configure the fields related to cross-device migration in the configuration file. 55 56 Configure the application to support migration. 57 Set the **continuable** field in the **module.json5** file to **true**. The default value is **false**. If this parameter is set to **false**, the application cannot be continued on the target device. 58 59 60 ```json 61 { 62 "module": { 63 ... 64 "abilities": [ 65 { 66 ... 67 "continuable": true, 68 } 69 ] 70 } 71 } 72 ``` 73 74 Configure the application launch type. For details, see [UIAbility Component Launch Type](uiability-launch-type.md). 75 764. Implement [onContinue()](../reference/apis/js-apis-app-ability-uiAbility.md#abilityoncontinue) in the UIAbility of the initiator. 77 [onContinue()](../reference/apis/js-apis-app-ability-uiAbility.md#abilityoncontinue) is called on the initiator. You can save the data in this method to implement application compatibility check and migration decision. 78 - Saving migrated data: You can save the data to be migrated in key-value pairs in **wantParam**. 79 80 - Checking application compatibility: You can obtain the version number of the target application from **wantParam** and check the compatibility between the target application and the current application. 81 82 - Making a migration decision: You can determine whether to support the migration based on the return value of **onContinue()**. For details about the return value, see [Available APIs](#available-apis). 83 84 The sample code is as follows: 85 86 ```ts 87 import UIAbility from '@ohos.app.ability.UIAbility'; 88 import AbilityConstant from '@ohos.app.ability.AbilityConstant'; 89 90 onContinue(wantParam : {[key: string]: any}) { 91 console.info(`onContinue version = ${wantParam.version}, targetDevice: ${wantParam.targetDevice}`) 92 let workInput = AppStorage.Get<string>('ContinueWork'); 93 // Set the user input data into wantParam. 94 wantParam["work"] = workInput // set user input data into want params 95 console.info(`onContinue input = ${wantParam["input"]}`); 96 return AbilityConstant.OnContinueResult.AGREE 97 } 98 ``` 99 1005. Implement **onCreate()** and **onNewWant()** in the UIAbility of the target application to implement data restoration. 101 - Implementation example of **onCreate** in the multi-instance scenario 102 - The target device determines whether the startup is **LaunchReason.CONTINUATION** based on **launchReason** in **onCreate()**. 103 - You can obtain the saved migration data from the **want** parameter. 104 - After data restoration is complete, call **restoreWindowStage()** to trigger page restoration. 105 106 ```ts 107 import UIAbility from '@ohos.app.ability.UIAbility'; 108 import AbilityConstant from '@ohos.app.ability.AbilityConstant'; 109 import distributedObject from '@ohos.data.distributedDataObject'; 110 111 export default class EntryAbility extends UIAbility { 112 storage : LocalStorage; 113 onCreate(want, launchParam) { 114 console.info(`EntryAbility onCreate ${AbilityConstant.LaunchReason.CONTINUATION}`) 115 if (launchParam.launchReason == AbilityConstant.LaunchReason.CONTINUATION) { 116 // Obtain the user data from the want parameter. 117 let workInput = want.parameters.work 118 console.info(`work input ${workInput}`) 119 AppStorage.SetOrCreate<string>('ContinueWork', workInput) 120 this.storage = new LocalStorage(); 121 this.context.restoreWindowStage(this.storage); 122 } 123 } 124 } 125 ``` 126 - For a singleton ability, use **onNewWant()** to achieve the same implementation. 127
