Mastering Application Continuation in HarmonyOS Next

Seamlessly continue your app experiences across multiple devices. This guide delves into the intricacies of application continuation in HarmonyOS Next, empowering you to build truly connected applications.

Basic Concepts and Application Scenarios

Application continuation in HarmonyOS Next allows users to effortlessly switch between devices while maintaining their app's state and progress. This involves sophisticated distributed state synchronization, ensuring a consistent experience regardless of the device being used.

Imagine reading an article on your phone and seamlessly continuing on your tablet from exactly where you left off. Or editing a document on your PC and picking up where you left off on your phone. These are just two examples of how application continuation enhances user experience and productivity.

Analyzing Application Continuation APIs

onContinue()

The onContinue() method is crucial for the source device (where the user initiates the continuation). This method is called when continuation is triggered. Here, you perform vital tasks like saving data necessary for migration.

Key operations within onContinue() include saving application state data (e.g., editor text, browser URL) in wantParam as key-value pairs. It's also essential to perform application compatibility checks. Check the target application's version number (wantParam.version) and compare it to the source version. Return an appropriate result (e.g., AbilityConstant.OnContinueResult.MISMATCH) if versions are incompatible, guiding the user with informative feedback.

import { AbilityConstant, UIAbility } from '@kit.AbilityKit';
import { promptAction } from '@kit.ArkUI';

export default class EntryAbility extends UIAbility {
    onContinue(wantParam: Record) {
        let targetVersion = wantParam.version; 
        let versionThreshold: number = 1; 
        if (targetVersion < versionThreshold) {
            promptAction.showToast({
                message: 'The target application version is too low to support continuation. Please upgrade the application version and try again.',
                duration: 2000
            });
            return AbilityConstant.OnContinueResult.MISMATCH;
        }
        let continueInput = 'Migrated data';
        if (continueInput) {
            wantParam["data"] = continueInput;
        }
        return AbilityConstant.OnContinueResult.AGREE;
    }
}

onCreate()

On the target device (the device where continuation resumes), the onCreate() method is used to restore the migrated data. Check launchParam.launchReason to confirm if it's a continuation launch. If so, retrieve the saved data from want.

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
    storage: LocalStorage = new LocalStorage();
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
        if (launchParam.launchReason == AbilityConstant.LaunchReason.CONTINUATION) {
            let continueInput = '';
            if (want.parameters != undefined) {
                continueInput = JSON.stringify(want.parameters.data);
                console.info(`continue input ${continueInput}`);
            }
            this.context.restoreWindowStage(this.storage);
        }
    }
}

onNewWant()

For single-instance applications, implement onNewWant(). Its functionality mirrors onCreate(): Check for continuation launches and restore data accordingly.

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
    storage: LocalStorage = new LocalStorage();
    onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
        console.info(`EntryAbility onNewWant ${AbilityConstant.LaunchReason.CONTINUATION}`);
        if (launchParam.launchReason == AbilityConstant.LaunchReason.CONTINUATION) {
            let continueInput = '';
            if (want.parameters != undefined) {
                continueInput = JSON.stringify(want.parameters.data);
                console.info(`continue input ${continueInput}`);
            }
            this.context.restoreWindowStage(this.storage);
        }
    }
}

Best Practices and Considerations

• Efficient Data Serialization: Choose efficient data serialization methods (JSON is commonly used) to minimize overhead and ensure fast data transfer between devices.
• Data Security: Securely handle sensitive data during migration, employing encryption or other appropriate security measures.
• Error Handling: Implement robust error handling to gracefully manage potential failures during the continuation process, providing users with informative feedback.
• Version Compatibility: Always check version compatibility to prevent unexpected behavior or crashes.

Conclusion

Application continuation is a powerful feature in HarmonyOS Next that significantly enhances user experience. By understanding and implementing the APIs presented in this guide, you can build more seamless and connected applications across various devices. Remember to prioritize data efficiency, security, and error handling to create a reliable and user-friendly application continuation experience.