Dev.to

Implementing AppLinking in HarmonyOS Next Atomic Services

Implementing AppLinking in HarmonyOS Next Atomic Services 1. Background Information Official Documentation: Atomic Service AppLinking Guide Key Requirements: Deep Linking: Parse pagePath parameter to navigate to specific pages within atomic services Link Generation: Create links programmatically for atomic service navigation Universal Usage: Links work both within apps and via external sources (SMS, websites, etc.) 2. AppLinkingUtils Implementation ```typescript import { common, Want, wantAgent } from '@kit.AbilityKit'; import { GlobalContext } from './GlobalContext'; import { router } from '@kit.ArkUI'; import { AppUtil } from './AppUtil'; import { BusinessError } from '@kit.BasicServicesKit'; import { LogUtil } from './LogUtil'; interface MessageReceivedParams { want?: Want; method: "onCreate" | "enterDnTabBarPage"; } /** * AppLinking Utility Class * Official Docs: https://developer.huawei.com/consumer/cn/doc/atomic-guides-V5/atomic-applinking-V5 */ export class AppLinkingUtils { /** * Handles incoming AppLinking requests * @param params Contains either launch parameters or navigation command */ static messageReceived(params: MessageReceivedParams) { // Process incoming link parameters if (params.want) { const want = params.want; const pagePath = want.parameters?.['pagePath'] as string; if (pagePath) { // Store target path for later navigation GlobalContext.getContext().setObject("appLinkingPagePath", pagePath); } } // Execute navigation when app is ready if (params.method === "enterDnTabBarPage") { const appLinkingPagePath = GlobalContext.getContext().getObject("appLinkingPagePath") as string; if (appLinkingPagePath) { // Clear stored path and navigate GlobalContext.getContext().deleteObject("appLinkingPagePath"); router.pushUrl({ url: appLinkingPagePath }); } } } /** * Opens an AppLinking URL * @param url The AppLinking URL to open */ static openLink(url: string) { const context: common.UIAbilityContext = AppUtil.getContext(); context.openLink(url) .then(() => { LogUtil.info('AppLinking opened successfully'); }) .catch((error: BusinessError) => { LogUtil.error(`AppLinking failed: ${JSON.stringify(error)}`); }); } } ``` 3. Integration Points 3.1 EntryAbility Integration ```typescript export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { // Initialize application context AppUtil.init(this.context); // Process AppLinking launch parameters AppLinkingUtils.messageReceived({ want: want, method: "onCreate" }); } } ``` 3.2 Main Page Integration ```typescript @Preview @Entry @Component struct DnTabBarPage { aboutToAppear() { // Execute AppLinking navigation when main page appears AppLinkingUtils.messageReceived({ method: "enterDnTabBarPage" }); } } ``` Implementation Workflow Link Creation: Create links in AppGallery Connect → AppLinking Configure pagePath parameter for deep linking Link Handling: When app launches via link, EntryAbility.onCreate() captures pagePath Path is stored in global context When main page loads, it checks for stored path and navigates Programmatic Usage: Use AppLinkingUtils.openLink() to navigate to atomic services Works for both in-app navigation and external triggers Key Features Deep Linking Support: Seamlessly navigates to specific pages within atomic services Maintains navigation state across app lifecycle Lifecycle Management: Separates link capture (onCreate) and execution (page ready) Ensures navigation only occurs when UI is prepared Error Handling: Comprehensive logging for debugging Graceful error handling for invalid links Global State Management: Uses GlobalContext to persist navigation targets Automatically cleans up after navigation Usage Examples 1. Creating AppLinking URLs ```typescript // Generated in AppGallery Connect const DEEP_LINK = "https://hoas.drcn.agconnect.link/9P7g?pagePath=pages/DetailPage"; ``` 2. Triggering Navigation ```typescript // Navigate to atomic service from within app AppLinkingUtils.openLink(DEEP_LINK); // Open via SMS (same link works externally) sendSMS("Check this out: " + DEEP_LINK); ``` 3. Handling Incoming Links ``` User clicks: https://hoas.drcn.agconnect.link/9P7g?pagePath=pages/DetailPage App flow: 1. EntryAbility captures pagePath ("pages/DetailPage") 2. Stores path in GlobalContext 3. Main page (DnTabBarPage) loads 4. Detects stored path and navigates to DetailPage ``` This implementation provides a complete solution for AppLinking in HarmonyOS Next atomic services, enabling both

Jun 27, 2025 - 03:20

Implementing AppLinking in HarmonyOS Next Atomic Services

1. Background Information

Official Documentation:

Atomic Service AppLinking Guide

Key Requirements:

Deep Linking: Parse pagePath parameter to navigate to specific pages within atomic services
Link Generation: Create links programmatically for atomic service navigation
Universal Usage: Links work both within apps and via external sources (SMS, websites, etc.)

2. AppLinkingUtils Implementation

```typescript
import { common, Want, wantAgent } from '@kit.AbilityKit';
import { GlobalContext } from './GlobalContext';
import { router } from '@kit.ArkUI';
import { AppUtil } from './AppUtil';
import { BusinessError } from '@kit.BasicServicesKit';
import { LogUtil } from './LogUtil';

interface MessageReceivedParams {
  want?: Want;
  method: "onCreate" | "enterDnTabBarPage";
}

/**
 * AppLinking Utility Class
 * Official Docs: https://developer.huawei.com/consumer/cn/doc/atomic-guides-V5/atomic-applinking-V5
 */
export class AppLinkingUtils {
  /**
   * Handles incoming AppLinking requests
   * @param params Contains either launch parameters or navigation command
   */
  static messageReceived(params: MessageReceivedParams) {
    // Process incoming link parameters
    if (params.want) {
      const want = params.want;
      const pagePath = want.parameters?.['pagePath'] as string;

      if (pagePath) {
        // Store target path for later navigation
        GlobalContext.getContext().setObject("appLinkingPagePath", pagePath);
      }
    }

    // Execute navigation when app is ready
    if (params.method === "enterDnTabBarPage") {
      const appLinkingPagePath = GlobalContext.getContext().getObject("appLinkingPagePath") as string;

      if (appLinkingPagePath) {
        // Clear stored path and navigate
        GlobalContext.getContext().deleteObject("appLinkingPagePath");
        router.pushUrl({ url: appLinkingPagePath });
      }
    }
  }

  /**
   * Opens an AppLinking URL
   * @param url The AppLinking URL to open
   */
  static openLink(url: string) {
    const context: common.UIAbilityContext = AppUtil.getContext();

    context.openLink(url)
      .then(() => {
        LogUtil.info('AppLinking opened successfully');
      })
      .catch((error: BusinessError) => {
        LogUtil.error(`AppLinking failed: ${JSON.stringify(error)}`);
      });
  }
}
```

3. Integration Points

3.1 EntryAbility Integration

```typescript
export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // Initialize application context
    AppUtil.init(this.context);

    // Process AppLinking launch parameters
    AppLinkingUtils.messageReceived({
      want: want,
      method: "onCreate"
    });
  }
}
```

3.2 Main Page Integration

```typescript
@Preview
@Entry
@Component
struct DnTabBarPage {
  aboutToAppear() {
    // Execute AppLinking navigation when main page appears
    AppLinkingUtils.messageReceived({
      method: "enterDnTabBarPage"
    });
  }
}
```

Implementation Workflow

Link Creation:
- Create links in AppGallery Connect → AppLinking
- Configure pagePath parameter for deep linking
Link Handling:
- When app launches via link, EntryAbility.onCreate() captures pagePath
- Path is stored in global context
- When main page loads, it checks for stored path and navigates
Programmatic Usage:
- Use AppLinkingUtils.openLink() to navigate to atomic services
- Works for both in-app navigation and external triggers

Key Features

Deep Linking Support:
- Seamlessly navigates to specific pages within atomic services
- Maintains navigation state across app lifecycle
Lifecycle Management:
- Separates link capture (onCreate) and execution (page ready)
- Ensures navigation only occurs when UI is prepared
Error Handling:
- Comprehensive logging for debugging
- Graceful error handling for invalid links
Global State Management:
- Uses GlobalContext to persist navigation targets
- Automatically cleans up after navigation

Usage Examples

1. Creating AppLinking URLs

```typescript
// Generated in AppGallery Connect
const DEEP_LINK = "https://hoas.drcn.agconnect.link/9P7g?pagePath=pages/DetailPage";
```

2. Triggering Navigation

```typescript
// Navigate to atomic service from within app
AppLinkingUtils.openLink(DEEP_LINK);

// Open via SMS (same link works externally)
sendSMS("Check this out: " + DEEP_LINK);
```

3. Handling Incoming Links

```
User clicks: https://hoas.drcn.agconnect.link/9P7g?pagePath=pages/DetailPage

App flow:
1. EntryAbility captures pagePath ("pages/DetailPage")
2. Stores path in GlobalContext
3. Main page (DnTabBarPage) loads
4. Detects stored path and navigates to DetailPage
```

This implementation provides a complete solution for AppLinking in HarmonyOS Next atomic services, enabling both deep linking from external sources and programmatic navigation within applications.