Introduction

Have you ever felt that traditional audio recording methods weren’t enough for you? Have you ever wanted to explore more?

Welcome to explore AudioCapturer.

The AudioCapturer is used to record Pulse Code Modulation (PCM) audio data. It is suitable if you have extensive audio development experience and want to implement more flexible recording features.

AudioCapturer

AudioCapturer

To make things easier for ourselves, we will create an @Observed class.

Create Recorder.ets under ../ets/service directory.

import { audio } from '@kit.AudioKit';

@Observed
export default class Recorder {
  private capturer?: audio.AudioCapturer;
  state: string = 'STATE_INVALID';

  get recording(): boolean {
    return this.state === 'STATE_RUNNING';
  }
}

Time to record. Let’s start with defining audio parameters. Create Constants.ets under the service directory.

import { audio } from '@kit.AudioKit';

export const streamInfo: audio.AudioStreamInfo = {
  samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_48000,
  channels: audio.AudioChannel.CHANNEL_2,
  sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
  encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW,
  channelLayout: audio.AudioChannelLayout.CH_LAYOUT_STEREO
};

You can play with these as you wish. We defined this as a separate parameter because we will use it for AudioCapturer and AudioRenderer.

Now we can record. We will start by creating an AudioCapturer object.

async start(filePath: string) {
  try {
    this.capturer = await audio.createAudioCapturer({
        capturerInfo: {
          source: audio.SourceType.SOURCE_TYPE_MIC,
          capturerFlags: 0
        },
        streamInfo: streamInfo
      });

      // rest will come here
  } catch (e) {
    console.error('start err:', e.code, e.message);
  }
}

After we have a capturer, we can attach listeners. Start with on('stateChange'). This will inform when the capturer’s state changes.

this.capturer.on('stateChange', (state: audio.AudioState) => {
  switch (state) {
    case audio.AudioState.STATE_INVALID:
      this.state = 'STATE_INVALID';
      break;
    case audio.AudioState.STATE_NEW:
      this.state = 'STATE_NEW';
      break;
    case audio.AudioState.STATE_PREPARED:
      this.state = 'STATE_PREPARED';
      break;
    case audio.AudioState.STATE_RUNNING:
      this.state = 'STATE_RUNNING';
      break;
    case audio.AudioState.STATE_STOPPED:
      this.state = 'STATE_STOPPED';
      break;
    case audio.AudioState.STATE_RELEASED:
      this.state = 'STATE_RELEASED';
      break;
    case audio.AudioState.STATE_PAUSED:
      this.state = 'STATE_PAUSED';
      break;
  }

  console.info(`audioCapturer state changed to: ${this.state}`);
});

Second, we can listen for audio interruptions and act accordingly. Here we will cover some cases; you can always add more.

this.capturer.on('audioInterrupt', (interruptEvent: audio.InterruptEvent) => {
  if (interruptEvent.forceType === audio.InterruptForceType.INTERRUPT_FORCE) {
    switch (interruptEvent.hintType) {
      case audio.InterruptHint.INTERRUPT_HINT_PAUSE:
      case audio.InterruptHint.INTERRUPT_HINT_STOP:
        this.stopAndRelease();
        break;
      default:
        console.info('Invalid interruptEvent');
        break;
    }
  }
});

Finally, we must attach on('readData'). This will be triggered periodically when the system must read an audio stream. Basically, when the capturer gets data from the microphone.

We will use this to save data to a file.

• First, define a parameter to store the file fd. And another one to track the file write location. We do not want to override existing data, right?

private fileFd?: number;
private fileWriteOffset: number = 0;

• Create/open file, store file fd.

const audioFile: fs.File = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE);
this.fileFd = audioFile.fd;
console.info(`file fd: ${this.fileFd}`);

this.fileWriteOffset = 0;

• Attach the listener. This will write incoming data into the file.

this.capturer?.on('readData', (buffer) => {
  console.info(`read | len: ${buffer.byteLength} | offset: ${this.fileWriteOffset} | fd: ${this.fileFd}`);
  fs.writeSync(this.fileFd, buffer, {
    offset: this.fileWriteOffset,
    length: buffer.byteLength
  });

  this.fileWriteOffset += buffer.byteLength;
});

And now, we can actually start the recorder.

await this.capturer.start();

AudioRenderer

To play recorded audio clips, we will use AudioRenderer. Create Player under service directory.

We will follow the same logic with the AudioCapturer. Create the AudioRenderer object, attach listeners, read the file, and play.

import { audio } from '@kit.AudioKit';
import { fileIo as fs } from '@kit.CoreFileKit';
import { streamInfo } from './Constants';

@Observed
export default class Player {
  private player?: audio.AudioRenderer;
  state: string = 'idle';
  private fileFd?: number;
  private fileReadOffset: number = 0;

  private async init(filePath: string) {
    try {
      this.player = await audio.createAudioRenderer({
        rendererInfo: {
          usage: audio.StreamUsage.STREAM_USAGE_MUSIC,
          rendererFlags: 0
        },
        streamInfo: streamInfo
      });

      this.player.on('outputDeviceChangeWithInfo', (deviceChangeInfo: audio.AudioStreamDeviceChangeInfo) => {
        if (this.state === 'STATE_RUNNING') {
          this.pause();
        }
      });

      this.player.on('audioInterrupt', (interruptEvent: audio.InterruptEvent) => {
        if (interruptEvent.forceType === audio.InterruptForceType.INTERRUPT_FORCE) {
          switch (interruptEvent.hintType) {
            case audio.InterruptHint.INTERRUPT_HINT_PAUSE:
              console.info('Force paused. Update playing status and stop writing');
              this.pause();
              break;
            case audio.InterruptHint.INTERRUPT_HINT_STOP:
              console.info('Force stopped. Update playing status and stop writing');
              this.stop();
              break;
            default:
              break;
          }
        }
      });

      this.player.on('stateChange', (state: audio.AudioState) => {
        switch (state) {
          case audio.AudioState.STATE_INVALID:
            this.state = 'STATE_INVALID';
            break;
          case audio.AudioState.STATE_NEW:
            this.state = 'STATE_NEW';
            break;
          case audio.AudioState.STATE_PREPARED:
            this.state = 'STATE_PREPARED';
            break;
          case audio.AudioState.STATE_RUNNING:
            this.state = 'STATE_RUNNING';
            break;
          case audio.AudioState.STATE_STOPPED:
            this.state = 'STATE_STOPPED';
            break;
          case audio.AudioState.STATE_RELEASED:
            this.state = 'STATE_RELEASED';
            break;
          case audio.AudioState.STATE_PAUSED:
            this.state = 'STATE_PAUSED';
            break;
        }

        console.info(`audioRenderer state changed to: ${this.state}`);
      });

      const audioFile: fs.File = fs.openSync(filePath, fs.OpenMode.READ_ONLY);
      this.fileFd = audioFile.fd; // Obtain the file FD.
      console.info(`file fd: ${this.fileFd}`);

      this.fileReadOffset = 0;

      this.player.on('writeData', (buffer) => {
        console.info(`writeData | len: ${buffer.byteLength} | offset: ${this.fileReadOffset} | fd: ${this.fileFd}`);
        try {
          const readLength = fs.readSync(this.fileFd, buffer, {
            offset: this.fileReadOffset,
            length: buffer.byteLength
          });

          this.fileReadOffset += readLength;

          if (readLength === 0) {
            console.info('stop now');
            this.player?.off('writeData');
            this.stop();
          }

          return audio.AudioDataCallbackResult.VALID;
        } catch (error) {
          console.error('Error reading file:', error);
          return audio.AudioDataCallbackResult.INVALID;
        }
      });

      await this.player.start();
    } catch (e) {
      console.error(`init err: ${e}`);
    }
  }

  async start(filePath: string) {
    try {
      if (!this.player) {
        console.info('init');
        await this.init(filePath);
      } else {
        console.info('start');
        await this.player.start();
      }
    } catch (e) {
      console.error('start err:', e);
    }
  }

  async pause() {
    this.player?.pause();
  }

  async stop() {
    try {
      await this.player?.stop();
      await this.player?.release();
      fs.closeSync(this.fileFd);
      this.player = undefined;
    } catch (e) {
      console.error('stop err:', e.code, e.message);
      throw new Error(e.message);
    }
  }
}

Ready, Set, Action

Let’s see things in action. First things first, we need microphone permission.

• Modify module.json5

"requestPermissions": [
  {
    "name": "ohos.permission.MICROPHONE",
    "reason": "$string:mic_reason",
    "usedScene": {
      "when": "inuse"
    }
  }
]

Modify Index.ets

import Player from '../service/Player';
import Recorder from '../service/Recorder';
import { abilityAccessCtrl, common, PermissionRequestResult, Permissions } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  private filePath: string = `${this.getUIContext().getHostContext()!.filesDir}/record.pcm`;
  @State recorder: Recorder = new Recorder();
  @State player: Player = new Player();

  aboutToAppear(): void {
    this.requestMicPermission();
  }

  build() {
    Column() {
      Text('Recorder State');
      Text(this.recorder.state);

      Button('Record / Stop')
        .size({ height: 40, width: '50%' })
        .onClick(() => {
          if (this.recorder.recording) {
            this.recorder.stopAndRelease();
          } else {
            this.recorder.start(this.filePath);
          }
        });

      Text('Player State');
      Text(this.player.state);

      Button('Play / Pause')
        .size({ height: 40, width: '50%' })
        .onClick(() => {
          if (this.player.state === 'STATE_RUNNING') {
            this.player.pause();
          } else {
            this.player.start(this.filePath);
          }
        });

      Button('Release')
        .size({ height: 40, width: '50%' })
        .onClick(() => {
          this.player.stop();
        });
    }
    .justifyContent(FlexAlign.Center)
    .height('100%')
    .width('100%');
  }

  async requestMicPermission() {
    const atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
    const context = this.getUIContext().getHostContext();
    const permissions: Permissions[] = ['ohos.permission.MICROPHONE'];

    try {
      // request permission from user
      let granted =
        (await (atManager.requestPermissionsFromUser(context,
          permissions) as Promise<PermissionRequestResult>)).authResults[0] === 0;
      if (!granted) {
        // request permission on settings
        granted = (await atManager.requestPermissionOnSetting(context, permissions))[0] ===
        abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;

        if (!granted) {
          await (this.getUIContext().getHostContext() as common.UIAbilityContext).terminateSelf();
        }
      }
    } catch (error) {
      const err: BusinessError = error as BusinessError;
      console.error(`Failed to check access token. Code is ${err.code}, message is ${err.message}`);
    }
  }
}

This will ask for microphone permission when users open the app.

Bonus

private filePath: string = `${this.getUIContext().getHostContext()!.filesDir}/record.pcm`;

Right now, we are recording audio into the record.pcm file. But you may have realized that if you try to record again, it will override the existing audio.

Let’s see how we can record audio so that it will not override the existing recording, but continue after that.

Easy, you only need to change the file open mode inside Recorder.

const audioFile: fs.File = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE | fs.OpenMode.APPEND);

Conclusion

That’s all, folks. We have seen how to use AudioCapturer and AudioRenderer. Keep up the good work.

You can check the project in GitHub: https://github.com/Explore-In-HMOS-Wearable/how-to-record-audio-over-audio

See you all in new adventures. :)

~ Fortuna Favet Fortibus

References

• Document
• Document

How to use AudioCapturer and AudioRenderer with ArkTS? was originally published in Huawei Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

The Asset Store Service (ASSET) provides a robust framework for the secure management of sensitive, short-form data such as application tokens and financial credentials. By leveraging the underlying universal keystore and AES256-GCM encryption within a Trusted Execution Environment (TEE), the service ensures data remains protected even in compromised system states. This article explores securing sensitive data using the Asset Store Kit, implementing TEE-backed encryption and biometric CRUD workflows.

Project Requirements

The objective is to design a secure storage workflow where access to a secret (e.g., an API token) requires explicit user authentication, such as a PIN, facial recognition, or fingerprint at the time of retrieval. The solution must adhere to the following:

• Store the secret encrypted in the Asset Store Service (Secure Kit).
• Enforce device lock and user authentication before returning plaintext.
• Support the full CRUD lifecycle (save, read, update, remove).
• Provide robust error handling and user-friendly messages.

Core Concepts and Configuration

The implementation utilizes the @kit.AssetStoreKit module. Key attributes used to define the security policy include:

• ALIAS: A unique identifier for the specific secret.
• ACCESSIBILITY: Sets the device state required for access (e.g., DEVICE_UNLOCKED).
• AUTH_TYPE: Defines the required verification method (PIN, Biometrics, or both).
• AUTH_VALIDITY_PERIOD: A grace window (typically 30–120s) where subsequent reads do not require re-authentication.

Authenticated Query Workflow

To maintain a high security posture, the retrieval process follows a three-step handshake:

1. preQuery: Generates a unique challenge from the Asset Service.
2. User Authentication: Validates the user’s identity via the system’s UserIAM, binding the result to the challenge.
3. query & postQuery: Finalizes the data retrieval and closes the secure session.

Technical Implementation

1. Choose an alias for the secret (e.g., secure_api_token_v1).
2. Save the secret with authentication requirements:

• ACCESSIBILITY=DEVICE_UNLOCKED
• REQUIRE_PASSWORD_SET=true
• AUTH_TYPE=ANY
• Optional: AUTH_VALIDITY_PERIOD=30–120s

3. Read with user authentication:

• Call asset.preQuery() → receive a challenge.
• Perform system authentication (PIN/biometric) bound to that challenge.
• Call asset.query() to fetch the data.
• Call asset.postQuery() with the challenge to close the flow.

4. Update and Remove follow the same pattern if user auth is required.

5. Implement robust error handling and map technical codes to clear UX messages.

Service Layer: assetAuthService.ets

This module encapsulates the logic for secure storage and authenticated access.

import { asset } from '@kit.AssetStoreKit';
import util from '@ohos.util';

const enc = new util.TextEncoder();
const dec = new util.TextDecoder();

function toBytes(s: string): Uint8Array {
  return enc.encode(s);
}
function fromBytes(b?: Uint8Array): string {
  return b ? dec.decode(b) : '';
}

export const TOKEN_ALIAS = 'secure_api_token_v1';

// 1) Save secret with authentication policy
export async function saveSecretWithPolicy(secret: string): Promise<void> {
  const attrs: asset.AssetMap = new Map();
  attrs.set(asset.Tag.ALIAS, toBytes(TOKEN_ALIAS));
  attrs.set(asset.Tag.SECRET, toBytes(secret));
  attrs.set(asset.Tag.ACCESSIBILITY, asset.Accessibility.DEVICE_UNLOCKED);
  attrs.set(asset.Tag.REQUIRE_PASSWORD_SET, true);
  attrs.set(asset.Tag.AUTH_TYPE, asset.AuthType.ANY);
  attrs.set(asset.Tag.AUTH_VALIDITY_PERIOD, 60_000); // 60s grace window

  try {
    await asset.add(attrs);
  } catch (e) {
    const code = (e as { code?: number | string }).code;
    if (String(code) === '24000003') {
      const upd: asset.AssetMap = new Map();
      upd.set(asset.Tag.ALIAS, toBytes(TOKEN_ALIAS));
      upd.set(asset.Tag.SECRET, toBytes(secret));
      await asset.update(upd);
      return;
    }
    throw e;
  }
}

// 2) Authenticated read
export async function readSecretWithUserAuth(
  doUserAuth: (challenge: Uint8Array) => Promise<Uint8Array>
): Promise<string | null> {
  const query: asset.AssetMap = new Map();
  query.set(asset.Tag.ALIAS, toBytes(TOKEN_ALIAS));

  const challenge: Uint8Array = await asset.preQuery(query);
  await doUserAuth(challenge);

  const results: Array<asset.AssetMap> = await asset.query(query);

  const handle: asset.AssetMap = new Map();
  handle.set(asset.Tag.AUTH_CHALLENGE, challenge);
  await asset.postQuery(handle);

  if (!results.length) return null;
  const secretBytes = results[0].get(asset.Tag.SECRET) as Uint8Array | undefined;
  return fromBytes(secretBytes);
}

// 3) Authenticated update
export async function updateSecretWithUserAuth(
  newValue: string,
  doUserAuth: (challenge: Uint8Array) => Promise<Uint8Array>
): Promise<void> {
  const query: asset.AssetMap = new Map();
  query.set(asset.Tag.ALIAS, toBytes(TOKEN_ALIAS));

  const challenge: Uint8Array = await asset.preQuery(query);
  await doUserAuth(challenge);

  const upd: asset.AssetMap = new Map();
  upd.set(asset.Tag.ALIAS, toBytes(TOKEN_ALIAS));
  upd.set(asset.Tag.SECRET, toBytes(newValue));
  await asset.update(upd);

  const handle: asset.AssetMap = new Map();
  handle.set(asset.Tag.AUTH_CHALLENGE, challenge);
  await asset.postQuery(handle);
}

// 4) Authenticated remove
export async function removeSecretWithUserAuth(
  doUserAuth: (challenge: Uint8Array) => Promise<Uint8Array>
): Promise<void> {
  const query: asset.AssetMap = new Map();
  query.set(asset.Tag.ALIAS, toBytes(TOKEN_ALIAS));

  const challenge: Uint8Array = await asset.preQuery(query);
  await doUserAuth(challenge);

  await asset.remove(query);

  const handle: asset.AssetMap = new Map();
  handle.set(asset.Tag.AUTH_CHALLENGE, challenge);
  await asset.postQuery(handle);
}

AuthPage.ets (Wearable UI with PIN keypad + Success screen)

import router from '@ohos.router';
import { readSecretWithUserAuth } from '../services/assetAuthService';

@Entry
@Component
struct AuthPage {
  @State pinInput: string = '';
  @State status: string = 'Enter PIN to unlock';

  private async onUnlock(): Promise<void> {
    try {
      const val = await readSecretWithUserAuth(async (challenge) => {
        // Here, PIN entry should be verified against system IAM
        // For demo, we just return empty
        return new Uint8Array(0);
      });
      this.status = `Unlocked: ${val ?? ''}`;
      router.pushUrl({ url: 'pages/AuthSuccessPage', params: { token: val ?? '' } });
    } catch (e) {
      this.status = 'Auth failed';
    }
  }

  build() {
    Column() {
      Text(this.status).fontSize(10).margin({ bottom: 6 }).fontColor('#fff')

      // PIN entry display
      Row() {
        Text('*'.repeat(this.pinInput.length)).fontSize(14).fontColor('#4CAF50')
      }.margin({ bottom: 8 })

      // Keypad grid
      GridRow() {
        ['1','2','3','4','5','6','7','8','9','Delete','0','Unlock'].forEach((label) => {
          Button(label)
            .height(28).width(48)
            .margin({ top: 4, bottom: 4, left: 2, right: 2 })
            .fontSize(10)
            .onClick(() => {
              if (label === 'Delete') {
                this.pinInput = this.pinInput.slice(0, -1);
              } else if (label === 'Unlock') {
                this.onUnlock();
              } else {
                this.pinInput += label;
              }
            })
        })
      }
    }
    .width('100%').height('100%')
    .backgroundColor('#000')
    .alignItems(HorizontalAlign.Center)
    .justifyContent(FlexAlign.Center)
  }
}

AuthSuccessPage.ets (After unlock)

import router from '@ohos.router';

@Entry
@Component
struct AuthSuccessPage {
  @State token: string = '';

  build() {
    Column() {
      Image($r('app.media.ic_success')).width(36).height(36).margin({ bottom: 8 })

      Text('Access Granted')
        .fontSize(12)
        .fontColor('#4CAF50')
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 6 })

      Text(`Token: ${this.token}`)
        .fontSize(9)
        .fontColor('#FFFFFF')
        .margin({ bottom: 10 })

      Button('Done')
        .width('60%').height(24).fontSize(9)
        .borderRadius(10).backgroundColor('#4CAF50')
        .onClick(() => router.back())
    }
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
    .width('100%').height('100%')
    .backgroundColor('#000')
  }
}

Test Results

• No lock screen set: Reads fail until user sets PIN/password.
• With lock screen: Read prompts for user auth.
• Grace period: Reads within validity window skip extra prompts.
• Update/Remove: Verified with same preQuery → auth → operation → postQuery pattern.
• Data integrity: Returned secret matches last saved; remove clears it.

Conclusion

By integrating the Asset Store Kit with mandatory user authentication, developers can protect critical application data against both digital attacks and unauthorized physical access. This layered security approach combining TEE encryption with real-time biometric verification is essential for modern applications handling high-value secrets.

References

• Document
• Document

Implementing User-Authenticated Access to Secrets with Asset Store Service was originally published in Huawei Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

Hi fellow devs.

Today, we will once more learn how to use our smart watches to emulate cards and make payments.

This article will cover HCE Payment for Lite Wearables. For ArkTS implementation, please check: How to Implement HCE Payment in Smart Wearables?

Configurations

Everything goes with an order, so do we. Modify config.json.

• Add permission:

"reqPermissions": [
  {
    "name": "ohos.permission.NFC_CARD_EMULATION",
    "reason": "NFC is used for payment.",
    "usedScene": {
      "when": "always"
    }
  }
]

• Add card emulation action

"skills": [
  {
    "entities": [
      "ohos.nfc.cardemulation.action.HOST_APDU_SERVICE"
    ],
    "actions": [
      "ohos.nfc.cardemulation.action.HOST_APDU_SERVICE"
    ]
  }
],

• Add paymentAid

"metaData": {
  "customizeData": [
    {
      "name": "paymentAid",
      "value": "325041592E5359532E4444463031" // Visa International
    },
    {
      "name": "paymentAid",
      "value": "A0000000031010" // Visa credit or debit
    },
    {
      "name": "paymentAid",
      "value": "A0000000041010" // Mastercard credit or debit
    }
  ]
}

An application identifier (AID) is used to address an application in the card or Host Card Emulation (HCE) if delivered without a card.

https://en.wikipedia.org/wiki/EMV

File Storage

import file from '@system.file';

As you know, Lite wearables do not have a relational database system. Thus, we will use file storage to store the Card and SUKs. We will not dive into details here. You can check the project for the implementation.

HCE

Let’s spend some money.

If you have read the ArkTS version, you know that the app can process payments in the foreground and background. Here, things are a bit different. We do not have a background mode. If the app is not open, the OS will open the app to process the payment.

import { deleteSuk, getCard, getNextSuk, hasCard, numberOfSuks } from './dataStore';
import cardEmulation from '@ohos.nfc.cardEmulation';
import router from '../common/js/router';

// TODO: this must match with config.json
const paymentAid = [
    '325041592E5359532E4444463031',
    'A0000000031010',
    'A0000000041010'
];

let card;
let sukIndex;
let sukData;

function initialize() {
    card = getCard();
    let { index, suk } = getNextSuk();
    sukIndex = index;
    sukData = suk;
    console.info(`initialize | ${JSON.stringify(card)} | ${sukIndex} | ${JSON.stringify(sukData)}`);
}

export function deleteHce() {
    card = sukIndex = sukData = null;
}

export function hce() {
    if (!card && hasCard()) {
        console.info('initialize');
        initialize();
    }

    let hce = new cardEmulation.HceService();
    hce.stop('com.hmosdemos.hcepaymentlite');
    hce.start('com.hmosdemos.hcepaymentlite', paymentAid);

    hce.on('hceCmd', async (data, err) => {
        console.info(`hceCmd: ${data}`);

        if (err) {
            console.error(err);
            throw new Error('Error!');
        }

        if (card && sukData) {
            console.info('make payment');
            // TODO: make payment
            // Basically payment is just a communication with the POS machine.
            // You just need to know what to send.
            // GOOD LUCK :)

            // send a dummy response
            const response = [0x47, 0x4F, 0x4F, 0x44, 0x20, 0x4C, 0x55, 0x43, 0x4B, 0x20, 0x3A, 0x29, 0x90, 0x00];
            hce.transmit(response, () => {
            });

            // simulate success
            // delete last suk
            deleteSuk(sukIndex);
            deleteHce();
            console.info(`payment success remaining suk: ${numberOfSuks()}`);

            // route to success page
            router.go('pages/cardTransferSuccess/cardTransferSuccess', { sukCount: numberOfSuks() });
        } else if (card) {
            console.info('route to no suk');
            // route to no suk page
            router.go('pages/noSuk/noSuk');
        } else {
            console.info(`no card | no suk | ${JSON.stringify(card)} | ${JSON.stringify(sukData)}`);
        }
    });
}

The process is as follows:

• When users open the app, the system will initialize the listener.
• Card and SUK are read from file storage.

card = getCard();
let { index, suk } = getNextSuk();
sukIndex = index;
sukData = suk;

• When the app gets data from a POS machine, it will process and send back an answer.

hce.transmit(response, () => {
});

Basically, payment is just a communication with the POS machine. You just need to know what to send.

To activate the HCE, we call this in index.js

onInit() {
    // ...
    hce();
},

Data

In normal cases, you might get card data from an API or from a mobile app. Here we will use mock data to simulate the process.

Within index.js we can define add and remove functions.

addCard() {
    addCard({
        name: 'My Lucky Card'
    });

    this.setCardName();

    addSuks([{}, {}, {}, {}, {}]);

    hce();
},

deleteCard() {
    deleteCard();
    this.setCardName();
    deleteHce();
}

UI

Let’s see things in action. On the index page, we will add the current card and the add/remove buttons.

<div class="container">
    <div id="topDiv">
        <div id="empty"></div>
        <div id="textDiv">
            <text style="font-size: 24px;">Contactless Payment</text>
            <text style="font-size: 20px;">{{ cardName }}</text>
        </div>

        <div id="buttonDiv">
            <div id="addButton" @click="addCard">
                <text style="font-size: 24px;">Add Card</text>
            </div>
            <div id="removeButton" @click="deleteCard">
                <text style="font-size: 24px;">Remove</text>
            </div>
        </div>
    </div>
</div>

Result

It is good, ain’t it? You can check the project for the rest.

Conclusion

That’s all for this article. We have covered host card emulation in Lite wearables.

You can check the project in GitHub: https://github.com/Explore-In-HMOS-Wearable/sportwatch-how-to-use-hce

See you all in new adventures. :)

~ Fortuna Favet Fortibus

References

• GitHub - Explore-In-HMOS-Wearable/sportwatch-how-to-use-hce
• EMV - Wikipedia
• Document

How to Implement HCE Payment in LiteWearables? was originally published in Huawei Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

Hello everybody.

Today, we will learn how to use our smart watches to emulate cards and make payments. Let’s roll.

But first, allow me to give you brief domain knowledge:

EMV is a payment method based on a technical standard developed by Europay, Mastercard, and Visa.

Developed for payment cards, Point Of Sale (POS) terminals, and automated teller machines (ATM)

An application identifier (AID) is used to address an application in the card or Host Card Emulation (HCE) device.

It is used to identify the type of product, so that all product issuers (Visa, Mastercard, etc.) must have their own application.

EMV uses predefined protocols for data transmission, and data is exchanged in application protocol data units (APDUs)

For more information, check: https://en.wikipedia.org/wiki/EMV

Configurations

Let’s start with configurations. Modify module.json5.

• Add permission

"requestPermissions": [
  {
    "name": "ohos.permission.NFC_CARD_EMULATION",
    "reason": "$string:NFC_reason"
  }
]

• Add card emulation action

"skills": [
  {
    "entities": [
      "entity.system.home"
    ],
    "actions": [
      "ohos.want.action.home",
      "ohos.nfc.cardemulation.action.HOST_APDU_SERVICE"
    ]
  }
],

• Add payment-aid

"metadata": [
  {
    "name": "payment-aid",
    "value": "325041592E5359532E4444463031" // Visa International
  {
    "name": "payment-aid",
    "value": "A0000000031010" // Visa credit or debit
  },
  {
    "name": "payment-aid",
    "value": "A0000000041010" // Mastercard credit or debit
  }
]

An application identifier (AID) is used to address an application in the card or Host Card Emulation (HCE) if delivered without a card.

https://en.wikipedia.org/wiki/EMV

RDB

We will use the relational database to store the Card and Suks. We will not go into details of the RDB. You can check the project for the implementation.

Let’s define our data models. We will create these under the model directory.

• Card.ets

export interface Card {
  name: string;
  // TODO: define rest of the parameters if needed
}

• SUK.ets

export interface SUK {
  // TODO: define necessary parameters
}

export interface DbSUK {
  id: number;
  suk: SUK;
}

In our app, there will be only one card and multiple SUKs. I can see you smiling and trying to understand why we have the DbSUK interface. In real-life scenarios, using the power of JS, you can convert a given JSON data to an object. So we use DbSUK to benefit from this power and store SUK data without defining all the parameters. Also, we need a PK for our database.

HceHandler

Here is the main deal. Let’s see what it is.

import { cardEmulation } from '@kit.ConnectivityKit';

This is the main character. As its name gives away, we use this kit to make our app emulate a bank card.

type rt = 'foreground' | 'background';

We will keep track of whether our app runs in the foreground or background. This is not necessary in many cases, but in our case, we will route the app to the success page after the card read operation is successfull and as you might guess route operation causes the app to fail if it is called in the background.

await HceHandler.hceService!.transmit(response);

This is how we send a response to the POS machine. Basically, payment is just a communication with the POS machine. You just need to know what to send.

import { cardEmulation } from '@kit.ConnectivityKit';
import { bundleManager } from '@kit.AbilityKit';
import { Rdb } from '../rdb/Rdb';
import { CardTable } from '../rdb/tables/CardTable';
import { SUKTable } from '../rdb/tables/SukTable';

type rt = 'foreground' | 'background';

export default class HceHandler {
  private constructor() {
  }

  private static hceService: cardEmulation.HceService | undefined | null = undefined;
  private static runType: rt = 'background';

  static runInBackground() {
    HceHandler.runType = 'background';
  }

  static enable(context: Context, _runType: rt, pageStack?: NavPathStack) {
    console.info('start enable');
    HceHandler.runType = _runType;
    // first check availability
    if (canIUse('SystemCapability.Communication.NFC.Core') && cardEmulation.hasHceCapability()) {
      try {
        const hceElementName: bundleManager.ElementName = {
          bundleName: 'com.hmosdemos.hcepayment', // TODO: this must match with the app's bundle
          abilityName: 'EntryAbility',
          moduleName: 'entry'
        };

        // TODO: this must match with module.json5
        const paymentAid = [
          '325041592E5359532E4444463031',
          'A0000000031010',
          'A0000000041010'
        ];

        HceHandler.hceService?.stop(hceElementName);
        HceHandler.hceService = new cardEmulation.HceService();
        HceHandler.hceService.start(hceElementName, paymentAid);

        HceHandler.hceService.on('hceCmd', async (err, data) => {
          console.info(`hceCmd ${data}`);
          if (err) {
            console.error(`HceHandler callback Error: ${err}`);
            return;
          }

          // get card data from db
          await Rdb.instance.init(context);
          const card = CardTable.get();
          const suk = SUKTable.getLast();

          if (card && suk) {
            // TODO: make payment
            // Basically payment is just a communication with the POS machine.
            // You just need to know what to send.
            // GOOD LUCK :)

            // send a dummy response
            const response = [0x47, 0x4F, 0x4F, 0x44, 0x20, 0x4C, 0x55, 0x43, 0x4B, 0x20, 0x3A, 0x29, 0x90, 0x00];
            await HceHandler.hceService!.transmit(response);

            // simulate success
            // delete last suk
            SUKTable.delete(suk);
            console.info(`payment success remaining suk: ${SUKTable.getCount()}`);

            // route to success page
            if (HceHandler.runType === 'foreground' && pageStack) {
              const lastPage = pageStack.getAllPathName().pop();
              if (lastPage === 'CardTransferSuccess' || lastPage === 'NoSuk') {
                pageStack.replacePath({ name: 'CardTransferSuccess' });
              } else {
                pageStack.pushPath({ name: 'CardTransferSuccess' });
              }
            }

          } else if (card && SUKTable.getCount() === 0) {
            // route to no suk page
            if (HceHandler.runType === 'foreground' && pageStack) {
              const lastPage = pageStack.getAllPathName().pop();
              if (lastPage === 'CardTransferSuccess') {
                pageStack.replacePath({ name: 'NoSuk' });
              } else if (lastPage !== 'NoSuk') {
                pageStack.pushPath({ name: 'NoSuk' });
              }
            }
          }
        });
      } catch (error) {
        console.error(`HceHandler errCode: ${error.code} errMessage: ${error.message}`);
      }
    }
  }
};

User Interface

• Success Page — CardReadSuccess.ets

import { SUKTable } from '../rdb/tables/SukTable';

@Component
export default struct CardTransferSuccess {
  @Consume('mainStack') pageStack: NavPathStack;
  sukCount: number = SUKTable.getCount();

  build() {
    NavDestination() {
      Column() {
        Column() {
          SymbolGlyph($r('sys.symbol.checkmark_circle_fill'))
            .fontColor([Color.Green])
            .fontSize(24)
            .margin({ bottom: 8 });
          Text(`Card Transfer Success, Remaining: ${this.sukCount}`);
        }
        .size({ width: '70%', height: '70%' })
        .alignItems(HorizontalAlign.Center)
        .justifyContent(FlexAlign.Center);
      }
      .size({ width: '100%', height: '100%' })
      .backgroundColor(Color.Black)
      .alignItems(HorizontalAlign.Center)
      .justifyContent(FlexAlign.Center);
    }
    .hideTitleBar(true);
  }
}

• NoSuk.ets

@Component
export default struct NoSuk {
  @Consume('mainStack') pageStack: NavPathStack;

  build() {
    NavDestination() {
      Column() {
        Column() {
          SymbolGlyph($r('sys.symbol.xmark_circle_fill'))
            .fontColor([Color.Red])
            .fontSize(24)
            .margin({ bottom: 8 });
          Text('No suk left.');
        }
        .size({ width: '70%', height: '70%' })
        .alignItems(HorizontalAlign.Center)
        .justifyContent(FlexAlign.Center);
      }
      .size({ width: '100%', height: '100%' })
      .backgroundColor(Color.Black)
      .alignItems(HorizontalAlign.Center)
      .justifyContent(FlexAlign.Center);
    }
    .hideTitleBar(true);
  }
}

• And finally, Index.ets

import CardTransferSuccess from '../components/CardTransferSuccess';
import NoSuk from '../components/NoSuk';
import { SUKTable } from '../rdb/tables/SukTable';
import HceHandler from '../util/HceHandler';
import CardVM from '../viewmodel/CardVM';

@Entry
@Component
struct Index {
  @Provide('mainStack') pageStack: NavPathStack = new NavPathStack();
  @State cardVM: CardVM = CardVM.getInstance();

  onPageShow(): void {
    HceHandler.enable(this.getUIContext().getHostContext()!, 'foreground', this.pageStack);
  }

  build() {
    Navigation(this.pageStack) {
      Stack() {
        Column() {
          Blank().layoutWeight(1);

          Column() {
            Text('Contactless Payment')
              .fontSize(12);

            Text(this.cardVM.card?.name ?? 'Card Not Found')
              .fontSize(10);
          }
          .alignItems(HorizontalAlign.Start)
          .padding(6)
          .backgroundColor(Color.Gray)
          .width('100%')
          .borderRadius(8);

          Blank().layoutWeight(1);

          Row() {
            Button('Add Card')
              .layoutWeight(1)
              .height(30)
              .type(ButtonType.Normal)
              .backgroundColor(Color.Green)
              .onClick(() => {
                CardVM.getInstance().add({ name: 'My Lucky Card' });
                SUKTable.add([{}, {}, {}, {}, {}]);
              });
            Button('Remove')
              .layoutWeight(1)
              .height(30)
              .type(ButtonType.Normal)
              .backgroundColor(Color.Red)
              .onClick(() => {
                CardVM.getInstance().delete();
                SUKTable.deleteAll();
              });
          };
        }
        .height('70%')
        .width('70%');
      }
      .backgroundColor(Color.Black)
      .height('100%')
      .width('100%');
    }
    .navDestination(this.pageMap)
    .hideToolBar(true);
  }

  @Builder
  pageMap(name: string) {
    if (name === 'CardTransferSuccess') {
      CardTransferSuccess();
    } else if (name === 'NoSuk') {
      NoSuk();
    }
  }
}

You may wonder what this is:

@State cardVM: CardVM = CardVM.getInstance();

Don’t worry. I got you.

In normal cases, you might get card data from an API or from a mobile app. Here we will use mock data to simulate the process, and CardVM to handle app state.

import { Card } from '../model/Card';
import { CardTable } from '../rdb/tables/CardTable';

@Observed
export default class CardVM {
  private static instance: CardVM;

  private constructor() {
  }

  public static getInstance(): CardVM {
    if (!CardVM.instance) {
      CardVM.instance = new CardVM();
    }
    return CardVM.instance;
  }

  card: Card | null = CardTable.get();

  add(card: Card) {
    this.delete()
    CardTable.add(card);
    this.card = card;
  }

  delete() {
    CardTable.delete()
    this.card = null;
  }
}

Result

Conclusion

That’s all for this article. We have covered host card emulation in smart wearables.

You can check the project in GitHub: https://github.com/Explore-In-HMOS-Wearable/how-to-use-hce

See you all in new adventures. :)

~ Fortuna Favet Fortibus

References

• GitHub - Explore-In-HMOS-Wearable/how-to-use-hce
• EMV - Wikipedia
• Document

How to Implement HCE Payment in Smart Wearables? was originally published in Huawei Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

HUAWEI Wear Engine is a sophisticated integration framework designed for developers to bridge the gap between applications on mobile phones and wearable devices. By leveraging this engine, developers can establish a seamless bidirectional communication channel, allowing phone-based apps to send messages, notifications, and data to Huawei wearables, while simultaneously retrieving real-time device status.

What are the Open Capabilities of Huawei Wear Engine SDK?

The Huawei Wear Engine SDK offers a comprehensive set of open capabilities that allow developers to utilize the unique hardware and software features of both phones and wearables through a unified set of APIs. These capabilities are categorized into several core functions:

🚩Basic device capabilities:

• Obtaining basic information about wearable devices: Phone applications can retrieve a list of paired Huawei wearable devices (specifically those supporting HarmonyOS). This includes identifying device names, types, and real-time status such as connection stability and app installation progress.
• App-to-app communications: A phone app and a wearable app can share messages and files (such as documents, images, and music).

🚩 Template-Based Notifications: Developers can push customized notifications from the phone to the wearable. These notifications are template-driven, allowing for personalized titles, body content, and interactive buttons.

🚩 User Status Monitoring: Apps can query or subscribe to critical user data, such as heart rate alerts and wearing status, providing a more context-aware user experience.

🚩 Device Identification: For authorized enterprise partners, the engine provides access to specific hardware identifiers, such as the device Serial Number (SN).

Real-World Scenarios Powered by Wear Engine Capabilities

The integration of the Huawei Wear Engine SDK facilitates a more efficient interaction between mobile and wearable platforms. The following scenarios demonstrate how developers can apply these open capabilities to solve practical user needs:

Distributed Collaboration Between Phones and Wearable Devices

• Receiving notifications for important events on the wrist. For example, any notifications for schedules, medications, or tasks set in your phone app, can be synced to the wearable app. This means that users can receive and view important notifications on their wearable devices without their phones.
• Introducing the brand new interactive experience to the wrist. For example, when users use a phone app to stream videos or listen to music, they can use their wearable device to perform remote controls such as pausing, skipping to the next video/song, or stopping playback.
• Achieving real-time collaboration between the phone and the wearable device. For example, a user can start navigation from your phone app and then receive real-time instructions from the wearable app for when to turn left, go straight, or turn right. So the user doesn’t have to take out their phone or hold it in their hand to check the route as they navigate.

Device Virtualization Between Phones and Wearable Devices

You can integrate the Wear Engine SDK into your phone app and do not need to develop the corresponding wearable app again.

• Obtaining real-time wearable status. For example, phone apps can obtain the wearable status of connection, wearing, and battery levels in real time, providing more value-added services for users.

Conclusion

The HUAWEI Wear Engine SDK represents a pivotal advancement in cross-device synergy, offering developers a streamlined framework to bridge the gap between smartphones and wearables. By facilitating seamless data exchange and providing access to critical device insights, it empowers the creation of a more cohesive and responsive user ecosystem.

Ultimately, integrating Wear Engine allows developers to transcend the limitations of standalone applications. By leveraging these open capabilities, you can deliver highly personalized, context-aware services that enhance user convenience and expand the technical boundaries of your digital offerings.

References

• Document
• Document

What are the Open Capabilities of Huawei Wear Engine SDK? was originally published in Huawei Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

The HarmonyOS build process is governed by a set of essential configuration files that define how an application is compiled, packaged, and deployed. Central to this architecture are hvigor-config.json5 and build-profile.json5. These files allow developers to manage the build environment, customize tool versions, and handle complex multi-product requirements. Understanding the hierarchy and specific roles of these configurations is fundamental to maintaining a stable and efficient development workflow in DevEco Studio.

Understanding HarmonyOS Build Configuration Files

The HarmonyOS build process relies on specific configuration files, primarily hvigor-config.json5 and build-profile.json5. these files define the environment, manage dependencies, and facilitate multi-product builds.

Project-Wide Build Settings: hvigor-config.json5

Located in the project’s hvigor directory, this file manages the build tool's execution environment. It contains:

• Version Management: Build tool versions and script dependency specifications.
• Execution Policies: Build tool capabilities, including log levels and execution strategies.
• Runtime Parameters: Configuration for the Node.js runtime and additional parameters passed to build scripts.

Structural Configuration: build-profile.json5

The build-profile.json5 file exists at both the project and module levels. It follows a hierarchical logic: if a buildOption is defined in both, the module-level setting takes precedence.

1. Project-Level Configuration

Stored in the root directory, this file defines the overarching application structure:

• Project Architecture: Lists all modules, their names, and physical paths.
• App Basics: Specifies the application name, SDK versions, and signature information.
• Multi-Product Targets: Configures specific product definitions and buildMode settings.

2. Module-Level Configuration

Each module contains its own profile to manage local build requirements:

• API and Targets: Defines the API model type and specific targets for multi-product builds.
• Build Customization: Manages compilation and packaging settings for ArkTS/C++ source code and project resources.

Conclusion

Efficiently managing hvigor-config.json5 and build-profile.json5 is critical for scaling HarmonyOS applications. While the former stabilizes the build environment, the latter provides the structural flexibility needed for multi-module and multi-product development. By mastering these configuration files, developers can ensure a predictable, reproducible, and highly customized build process within DevEco Studio.

References

• Document
• Document
• Document
• Document

What are the HarmonyOS Build Process Configuration Files? was originally published in Huawei Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

In the modern app ecosystem, data privacy isn’t just a feature it’s a requirement. Whether you are handling sensitive user data or securing communications between a client and a server, choosing the right cryptographic tools is essential.

Enter the Crypto Architecture Kit, a robust framework designed to provide high-level cryptographic functionalities while shielding developers from the complexities of underlying third-party libraries.

What is the Crypto Architecture Kit?

The Crypto Architecture Kit acts as an abstraction layer for cryptographic operations. By providing a unified interface, it allows developers to implement complex security features without needing to worry about the implementation differences of various third-party libraries. Currently, the kit primarily leverages OpenSSL to deliver its capabilities.

Core Capabilities

The kit covers nearly every standard cryptographic requirement:

• Encryption & Decryption: Protecting data at rest and in transit.
• Signing & Verification: Ensuring data integrity and authenticity.
• Message Authentication Codes (MAC): Verifying that a message has not been tampered with.
• Key Agreement & Derivation: Securely establishing and expanding cryptographic keys.
• Message Digest (MD): Generating unique fingerprints for your data.
• Random Number Generation: Creating secure, unpredictable seeds for security protocols.

Understanding the Fundamentals

To use the kit effectively, it is vital to distinguish between the two primary types of cryptography it supports:

1. Symmetric Keys

In symmetric cryptography, a single key is used for both encryption and decryption. It is fast and efficient for bulk data, but it requires both the sender and receiver to share the same secret key securely.

2. Asymmetric Keys

Asymmetric cryptography uses a key pair: a Public Key and a Private Key.

• For Encryption: Data encrypted with a public key can only be decrypted by the corresponding private key.
• For Signing: A user signs data with their private key, and anyone with the public key can verify that the signature is authentic.

Constraints and Best Practices

While the Crypto Architecture Kit is powerful, developers must be aware of its specific operational constraints to avoid security pitfalls:

• No Multi-threading: The kit does not currently support multi-thread concurrent operations. Ensure your cryptographic calls are handled within a single-thread context or managed via serial queues.
• Algorithm Selection: While the kit supports a wide range of algorithms, not all are created equal. Legacy algorithms like MD5 are available but are not recommended for high-security scenarios due to vulnerabilities. Always choose modern specifications (like AES or RSA-2048+) based on your specific service requirements.
• Key Management: A crucial distinction to remember is that this kit provides operations, not storage. It is designed for keys held in memory (like temporary session keys).

Pro Tip: If your application requires long-term, secure key storage (such as protecting a master key at the hardware level), you should pair this kit with the Universal Keystore Kit.

Why Use It?

The primary advantage of the Crypto Architecture Kit is the elevation of the developer experience. By providing a consistent API, it reduces the boilerplate code usually required to interface directly with libraries like OpenSSL. This leads to cleaner codebases, fewer implementation errors, and more secure applications.

Conclusion

The Crypto Architecture Kit represents a significant step forward for developers who need to balance robust security with development efficiency. By abstracting the complexities of OpenSSL and providing a unified interface for everything from MAC generation to key agreement, it allows you to focus on building features rather than wrestling with cryptographic specifications.

However, remember that great power comes with the responsibility of implementation:

• Be Mindful of Threading: Keep your operations synchronous and avoid concurrent calls to prevent errors.
• Prioritize Modern Standards: Steer clear of legacy algorithms like MD5 in favor of more secure alternatives provided within the kit.
• Layer Your Security: Use the Crypto Architecture Kit for the “work” (encryption/signing) and the Universal Keystore Kit for the “vault” (long-term key storage).

By understanding these boundaries and leveraging the kit’s comprehensive capability scope, you can ensure your application’s data remains uncompromised and your user experience stays seamless.

References

• Document
• Document
• Document
• Document

Securing Apps with Crypto Architecture Kit in HarmonyOS Next was originally published in Huawei Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

DevEco Studio simplifies the documentation process through its integrated Generate ArkTSDoc feature. This tool enables developers to efficiently produce structured reference documentation for exported variables, methods, APIs, and classes directly from the source code. By automating the extraction of technical details, it ensures that project interfaces are accurately documented and easily accessible, fostering better maintainability and collaboration within the HarmonyOS ecosystem.

Implementation and Key Requirements

1. On the menu bar, choose Tools > Generate ArkTSDoc… to open the Generate ArkTSDoc dialog box.
2. Set the scope for the documentation generation and the output directory.

3. To enable the ArkTSDoc documentation to automatically open in the browser after being generated, select Open generated documentation in browser. When you are done, click Generate to start the scanning and documentation generation.

The left panel of the generated ArkTSDoc mirrors your project’s directory structure, while the right panel allows you to navigate to specific variables, methods, APIs, or classes in the documentation.

If the Open generated documentation in browser option is not selected, a notification will pop up in the lower right corner of DevEco Studio after the documentation is generated. You can click Go to Folder to navigate to the generated ArkTSDoc folder and open the index.html file in a browser to view the documentation.

Key Technical Constraints:

Supported Formats: Documentation can be generated for .ets, .ts, .js, and .md files.

Export Visibility: Only exported variables, methods, APIs, and classes are included; internal, unexported items are automatically excluded.

Structure Preservation: The generated ArkTSDoc maintains the original project or directory hierarchy for seamless navigation.

Conclusion

The Generate ArkTSDoc feature in DevEco Studio is an essential tool for maintaining high-quality technical standards in HarmonyOS development. By automating the transition from source code to professional documentation, it eliminates manual overhead and ensures that your API remains clear and navigable. Adopting this workflow not only improves internal project organization but also provides external collaborators with the structured information necessary for successful integration.

References

• Document
• Document

How to Generate ArkTSDoc in DevEco Studio was originally published in Huawei Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

In this article, we will talk about the Gesture events for HarmonyOS Next.

Gesture events in HarmonyOS ArkTS enable developers to handle user interactions such as taps, long presses, pans, pinches, and swipes.

These events are essential for creating responsive and intuitive UI components. This document provides a detailed guide on implementing gesture binding, single gestures, combined gestures, multi-level gesture events, and gesture judgment logic.s

Understanding the ArkTS Gesture Events

HarmonyOS ArkTS provides a flexible gesture system that allows developers to bind gestures to UI components, prioritize gestures, and handle complex interactions. Key concepts include:

• Gesture Binding: Associating gestures with components using .gesture(), .priorityGesture(), and .parallelGesture().
• Single Gestures: Individual interactions like taps, long presses, pans, pinches, and swipes.
• Combined Gestures: Layered or simultaneous interactions using GestureGroup with modes like Sequence, Parallel, and Exclusive.
• Multi-level Gesture Events: Handling gestures in nested UI hierarchies with responseRegion and hitTestBehavior.
• Gesture Judgment: Resolving conflicts and prioritizing gestures using APIs like onGestureJudgeBegin and shouldBuiltInRecognizerParallelWith.

Implementation Steps

Gesture Binding

.gesture(): Bind a single gesture to a component.

Example: Tap, LongPress, Pan, Pinch, Rotation, or Swipe gestures.

.priorityGesture(): Prioritize parent gestures over child components.

Example: Ensure parent components respond to gestures even if child components are overlapping.

.parallelGesture(): Enable both parent and child components to respond to the same gesture.

Example: Simultaneous pan gestures on nested components.

Single Gesture

1. Define the gesture type: Use TapGesture, LongPressGesture, PanGesture, RotationGesture,SwipeGesture .
2. Bind the gesture: Use .gesture() to associate the gesture with a component.
3. Implement action logic: Use .onAction() to define the behavior triggered by the gesture.

Example code snippets:

Tap Gesture

Text("Tap Me")  
  .gesture(TapGesture({ count: 2 })  
    .onAction(() => {  
      console.info("Double tap detected");  
    })  
  )

Long Press Gesture

Text("LongPress OnAction:" + this.count)  
  .gesture(LongPressGesture({ repeat: true })  
    .onAction(() => {  
      this.count++;  
    })  
  )

Pan Gesture

Text("PanGesture Offset:\nX: " + this.offsetX + "\nY: " + this.offsetY)  
  .gesture(PanGesture()  
    .onActionUpdate((event) => {  
      this.offsetX = event.offsetX;  
      this.offsetY = event.offsetY;  
    })  
  )

Pinch Gesture

Column()  
  .scale({ x: this.scaleValue, y: this.scaleValue })  
  .gesture(PinchGesture({ fingers: 3 })  
    .onActionUpdate((event) => {  
      this.scaleValue = event.scale;  
    })  
  )

Rotation Gesture

Text("RotationGesture angle:" + this.angle)  
  .rotate({ angle: this.angle })  
  .gesture(RotationGesture()  
    .onActionUpdate((event) => {  
      this.angle = event.angle;  
    })  
  )

Swipe Gesture

Column()  
  .rotate({ angle: this.rotateAngle })  
  .gesture(SwipeGesture({ direction: SwipeDirection.Vertical })  
    .onAction((event) => {  
      this.rotateAngle = event.angle;  
    })  
  )

Combined Gestures

1. Use GestureGroup: Combine multiple gestures with GestureMode (Sequence, Parallel, Exclusive).
2. Define parameters: Adjust count, distance, speed, fingers, etc., to customize gesture behavior.
3. Handle recognition: Use .onAction() or .onActionUpdate() to process gesture events.

Combined Gestures Examples

Parallel Recognition

gesture(GestureGroup(GestureMode.Parallel,  
  TapGesture({ count: 1 })  
    .onAction(() => { this.count1++; }),  
  TapGesture({ count: 2 })  
    .onAction(() => { this.count2++; })  
))

Exclusive Recognition

gesture(GestureGroup(GestureMode.Exclusive,  
  TapGesture({ count: 1 })  
    .onAction(() => { this.count1++; }),  
  TapGesture({ count: 2 })  
    .onAction(() => { this.count2++; })  
))

Multi-level Gesture Events

1. Use responseRegion: Control the touch target area of a component.
2. Set hitTestBehavior: Define how components interact with touch events (Block, Transparent, None).
3. Manage priority: Use .priorityGesture() or .parallelGesture() to control gesture priority.

Gesture Judgment

1. Use onGestureJudgeBegin: Dynamically decide whether to trigger a gesture based on component state.
2. Use shouldBuiltInRecognizerParallelWith: Control parallel gesture recognition between nested components.
3. Adjust recognizer states: Enable or disable gesture recognizers based on the boundary.

Gesture Judgment Examples

shouldBuiltInRecognizerParallelWith

.shouldBuiltInRecognizerParallelWith((current, others) => {  
  for (let i = 0; i < others.length; i++) {  
    let target = others[i].getEventTargetInfo();  
    if (target.getId() == "inner" && others[i].isBuiltIn() && others[i].getType() == GestureControl.GestureType.PAN_GESTURE) {  
      return others[i];  
    }  
  }  
  return undefined;  
})

onGestureRecognizerJudgeBegin

.onGestureRecognizerJudgeBegin((event, current, others) => {  
  let target = current.getEventTargetInfo();  
  if (target.getId() == "outer" && current.isBuiltIn() && current.getType() == GestureControl.GestureType.PAN_GESTURE) {  
    for (let i = 0; i < others.length; i++) {  
      let target = others[i].getEventTargetInfo() as ScrollableTargetInfo;  
      if (target instanceof ScrollableTargetInfo && target.getId() == "inner") {  
        let panEvent = event as PanGestureEvent;  
        this.childRecognizer.setEnabled(true);  
        this.currentRecognizer.setEnabled(false);  
        if (target.isEnd()) {  
          if (panEvent && panEvent.offsetY < 0) {  
            this.childRecognizer.setEnabled(false);  
            this.currentRecognizer.setEnabled(true);  
          }  
        }  
      }  
    }  
  }  
  return GestureJudgeResult.CONTINUE;  
})

Considerations

Conflict Resolution:

• Use responseRegion and hitTestBehavior to avoid unintended behavior in nested hierarchies.
• Test thoroughly to resolve conflicts between parent and child components.

Performance:

• Optimize gesture parameters (e.g., distance, speed, count) for smooth interactions.
• Avoid overusing gestures in complex UIs to prevent performance issues.

User Experience:

• Ensure gestures align with user expectations (e.g., long press feedback).
• Provide visual or auditory feedback for gestures like taps and swipes.

Testing:

• Always test on real devices to ensure expected behavior in nested hierarchies.
• Validate gesture recognition under different conditions (e.g., overlapping components, touch targets).

Conclusion

HarmonyOS ArkTS provides a flexible gesture system for creating rich, interactive UIs with precise control over taps, swipes, and multi-touch. It helps you connect these gestures to buttons and other parts of your app. You can also decide which gesture is more important when there are two together. This system is very useful for making apps that feel natural and fun for people to use.

References

• Document
• Document
• Document
• Document

Gesture Events in HarmonyOS Next -ArkTS was originally published in Huawei Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.

Introduction

Modern applications rarely run in a single environment. Most teams need development, staging, and production setups — each with different API endpoints, logging rules, and analytics behavior.
The real challenge is doing this cleanly, without scattering if (debug) conditions across your code or maintaining multiple projects.

In this article, we’ll walk through a production-ready approach to environment switching in HarmonyOS using Build Modes and ArkTS, fully aligned with how DevEco Studio is designed to work.

Why Build Modes Are the Right Tool

DevEco Studio supports Build Modes such as debug, stage, and release.
Each build mode can inject compile-time constants into your app via build-profile.json5.

These values are:

• Defined once at the project level
• Automatically compiled into a generated BuildProfile
• Accessible directly from the ArkTS code
• Switched without touching application logic

This gives us environment isolation similar to Gradle BuildConfig on Android or flavors — but with a cleaner ArkTS-native flow.

What We Want to Achieve

Our goal is to switch environments only by selecting a Build Mode, while ArkTS code automatically receives the correct configuration:

No manual edits. No runtime flags. No branching logic.

Step 1: Define Environment Variables in Build Modes

Open your project-level build-profile.json5 and define environment-specific values under buildModeSet.

"buildModeSet": [
  {
    "name": "debug",
    "buildOption": {
      "debuggable": true,
      "arkOptions": {
        "buildProfileFields": {
          "API_URL": "dev.example.com",
          "ENABLE_LOGGING": true,
          "ENABLE_ANALYTICS": false
        }
      }
    }
  },
  {
    "name": "stage",
    "buildOption": {
      "debuggable": false,
      "arkOptions": {
        "buildProfileFields": {
          "API_URL": "stage.example.com",
          "ENABLE_LOGGING": true,
          "ENABLE_ANALYTICS": true
        }
      }
    }
  },
  {
    "name": "release",
    "buildOption": {
      "debuggable": false,
      "arkOptions": {
        "buildProfileFields": {
          "API_URL": "prod.example.com",
          "ENABLE_LOGGING": false,
          "ENABLE_ANALYTICS": true
        }
      }
    }
  }
]

Each build mode now represents a fully isolated environment.

Step 2: Ensure Modules Are Linked to a Product

Your modules must be attached to a product for Build Modes to apply correctly.

"modules": [
  {
    "name": "entry",
    "srcPath": "./entry",
    "targets": [
      {
        "name": "default",
        "applyToProducts": ["default"]
      }
    ]
  }
]

This is a common oversight — without it, Build Modes may not propagate.

Step 3: Build and Inspect the Generated BuildProfile

After selecting a Build Mode (for example, stage) and building the project,

DevEco Studio generates:

entry/build/default/generated/profile/default/BuildProfile.ets

Example output:

export const BUILD_MODE_NAME = 'stage';
export const DEBUG = false;
export const API_URL = 'stage.example.com';
export const ENABLE_LOGGING = true;
export const ENABLE_ANALYTICS = true;

export default class BuildProfile {
  static readonly API_URL = API_URL;
  static readonly ENABLE_LOGGING = ENABLE_LOGGING;
  static readonly ENABLE_ANALYTICS = ENABLE_ANALYTICS;
}

⚠️ Important
This file is auto-generated.
Do not edit it manually — its contents change based on the selected Build Mode.

Step 4: Access Environment Variables in ArkTS

Using the generated values in ArkTS is straightforward.

import BuildProfile from 'BuildProfile';

@Entry
@Component
struct Index {
  @State apiUrl: string = BuildProfile.API_URL;
  @State loggingEnabled: boolean = BuildProfile.ENABLE_LOGGING;
  @State analyticsEnabled: boolean = BuildProfile.ENABLE_ANALYTICS;

  aboutToAppear(): void {
    console.log(`API_URL: ${this.apiUrl}`);
    console.log(`ENABLE_LOGGING: ${this.loggingEnabled}`);
    console.log(`ENABLE_ANALYTICS: ${this.analyticsEnabled}`);
  }

  build() {
    // UI Components
  }
}

No conditionals.
No runtime switches.
Everything is resolved at build time.

Test Results

✔ No code changes required
✔ BuildProfile regenerated correctly
✔ Safe and predictable configuration per environment

Why This Approach Scales Well

• Clean architecture — no environment logic leaking into business code
• Safe releases — production builds cannot accidentally log or hit dev APIs
• Team-friendly — environment switching is a one-click operation in DevEco Studio
• CI/CD ready — build mode selection fits naturally into pipelines

If you’re building wearable or multi-module HarmonyOS apps, this pattern scales effortlessly.

Conclusion

Build Modes + buildProfileFields provide one of the cleanest environment-switching mechanisms in the HarmonyOS ecosystem.
Once set up, your ArkTS code becomes environment-agnostic, and your builds become deterministic and safe.

If you’re coming from Android flavors or Flutter flavors — this is the HarmonyOS-native way to do it.

References

• Document
• Document

Implementing Environment Switching in HarmonyOS ArkTS with Build Modes was originally published in Huawei Developers on Medium, where people are continuing the conversation by highlighting and responding to this story.