陈杨

Posted on Jun 25

HarmonyOS5 Cloud Service Technology Sharing--Account Link Development Guide

#arkts

👋 Hello everyone! Today let's talk about how to implement the account linking feature in HarmonyOS application development using ArkTS (API 12). Whether it's a social app, a game, or a utility app, the account system is a crucial part of the user experience. With flexible account linking, users can log in using various methods like mobile phone, email, or HUAWEI ID, and can also freely link or unlink accounts, making user management more convenient!

🌟 Why Implement Account Linking?

Imagine a user first registers for your app with a mobile number, and later wants to switch to logging in with an email address without losing their original data—this is where account linking comes in handy! By linking multiple authentication methods, users can log in with any of them, and the system will recognize it as the same account, seamlessly synchronizing data. At the same time, developers can manage user behavior with a unified user ID, improving operational efficiency.

📋 Prerequisites

Enable Service: Enable "Auth Service" in the AppGallery Connect console.
Integrate SDK: Integrate the @hw-agconnect/auth package into your project.
Configure Application: Ensure that supported authentication methods (e.g., mobile, email, HUAWEI ID) have been added.

🔗 3 Ways to Link Accounts (with Code)

1️⃣ Link Mobile Number

A user is already logged in with another method (e.g., email) and wants to link their mobile number:

import auth from '@hw-agconnect/auth';
import { hilog } from '@kit.PerformanceAnalysisKit';

auth.getCurrentUser().then((user: AuthUser | null) => {
  user!.link({
    kind: "phone",
    phoneNumber: "180****1485",
    countryCode: "86",
    verifyCode: "123456" // In actual development, get this from an SMS message
  }).then(() => {
    hilog.info(0x0000, 'AuthDemo', 'Mobile number linked successfully!');
  }).catch((error: Error) => {
    hilog.error(0x0000, 'AuthDemo', `Linking failed: ${error.message}`);
  });
});

Note: You need to call the SMS verification API to get the verification code first.

2️⃣ Link Email Address

A user wants to link an email address as an alternative login method:

user!.link({
  kind: "email",
  email: "user@example.com",
  password: "SecurePassword123!", // Optional (if a password is already set)
  verifyCode: "7890" // Get this from an email verification code
}).then(() => {
  hilog.info(0x0000, 'AuthDemo', 'Email linked successfully!');
});

3️⃣ Link HUAWEI ID

One-click linking for HUAWEI ID, suitable for apps within the ecosystem:

user!.link({ kind: "hwid" })
  .then(() => hilog.info(0x0000, 'AuthDemo', 'HUAWEI ID linked successfully!'));

⚠️ Pitfall Guide

Uniqueness Constraint: Each authentication method can only be linked to one account (e.g., you cannot link two different mobile numbers).
Sensitive Operation Protection: Operations like changing the password or unlinking an account must be completed within 5 minutes of logging in. Re-authentication is required if this period is exceeded.
Keep at Least One Account: The last authentication method cannot be unlinked, to prevent account loss.

🔓 How to Unlink an Account?

When a user wants to cancel a login method (ensure at least one method remains):

// Unlink mobile number
auth.getCurrentUser().then(user => {
  user.unlink("phone")
    .then(() => hilog.info(0x0000, 'AuthDemo', 'Mobile number has been unlinked!'));
});

💡 Advanced Tips

Unified User Profile: Get a unique ID via user.getUid(), regardless of which method the user logs in with.
Exception Handling: Wrap sensitive operations in a try-catch block to provide user-friendly error messages:

catch((error: Error) => {
  if (error.code === '2032') {
    alert('Verification code is incorrect, please request a new one!');
  }
});

Multi-device Sync: Linking/unlinking operations are synchronized in real-time across all logged-in devices.

🎯 Best Practice Scenarios

User Experience Upgrade: When converting an anonymous user, link a mobile/email to retain data.
Merge Duplicate Accounts: Prompt for linking when the system detects the same user registering with different methods.
Security Enhancement: Guide users to link a second verification method as a backup login.

🚀 Conclusion

With ArkTS's account linking feature, developers can easily build a flexible and secure user system. Whether it's for improving user experience or optimizing backend management, this is an indispensable part of HarmonyOS application development. Get started and try it out! If you encounter any issues, feel free to leave a comment and discuss~

✨ Mini-Interaction: What "nightmares" have you encountered with account systems in your development? Feel free to share your stories!

I hope this guide becomes a useful handbook on your HarmonyOS development journey. Stay tuned! 👨‍💻🚀

DEV Community