aigens-sdk-huawei

Web-side plugin for Aigens BYOD apps running inside HarmonyOS WebView.

Documentation

• API Docs - Generated TypeDoc API reference for all classes, interfaces and functions.

Installation

npm install aigens-sdk-huawei
Copy

Quick Start

import { isHuaWei, getHuaweiCore } from 'aigens-sdk-huawei';
import { Core } from '@aigens/aigens-sdk-core';

// Auto-detect environment and pick the right Core
const activeCore = isHuaWei() ? getHuaweiCore() : Core;

// Use it like regular Core
const { member } = await activeCore.getMember({});
const { deeplink } = await activeCore.getDeeplink({});
await activeCore.dismiss({ closedData: { status: 'done' } });
Copy

API

isHuaWei(): boolean

Detects HarmonyOS WebView via User-Agent. Cached after first call.

getHuaweiCore(): CorePlugin

Returns a singleton CoreHuawei instance (drop-in replacement for Capacitor Core).

CorePlugin Methods

All methods route through JS Bridge to HarmonyOS native.

getMember(options): Promise<{ member: Member }>

Returns current member info.

interface Member {
  deviceId: string;
  memberCode?: string;
  source?: string;
  sessionId?: string;
  appScheme?: string;
  universalLink?: string;
  name?: string;
  email?: string;
  phone?: string;
}
Copy

getDeeplink(options): Promise<{ deeplink: Deeplink }>

Returns launch deeplink parameters.

interface Deeplink {
  addItemId?: string;
  addDiscountCode?: string;
  addOfferId?: string;
  addOrder?: string;
}
Copy

dismiss(options): Promise<any>

Closes the WebView and returns data to native.

finish(options): Promise<any>

Same as dismiss.

isInstalledApp(options: { key: string }): Promise<{ install: boolean }>

Checks if an app is installed.

isDebug(): Promise<{ debug: boolean }>

Returns whether debug mode is active.

openExternalUrl(options: { url: string }): Promise<any>

Opens a URL in the system browser.

setTextZoom(options: { value: number }): Promise<any>

Sets text zoom level (0–1).

readClipboard(): Promise<{ value: string; type: 'text/plain' }>

Reads clipboard content.

makeHKFPSPayment(options: FPSPaymentOptions): Promise<FPSResultOptions>

Initiates HK FPS payment.

interface FPSPaymentOptions {
  paymentRequestUrl: string;
  callbackUrl?: string;
  typeIdentifier?: string;
  title?: string;
}

interface FPSResultOptions {
  result: boolean;
  url?: string;
  intent?: string;
}
Copy

setNativeBackPressEnabled(options: { enable: boolean }): Promise<{ enabled: boolean }>

Controls whether the system back press (swipe / back button) is handled by the native WebView container.

• enable: true (default): back press navigates the WebView back in history; if no history, dismisses the WebView.
• enable: false: back press is completely ignored while the WebView is open (swipe does nothing). dismiss() still works programmatically. After the WebView is dismissed, the host app's normal back behavior is automatically restored.

const core = getHuaweiCore();

// Disable native back press — swipe / back button do nothing
await core.setNativeBackPressEnabled({ enable: false });

// Re-enable default behavior
await core.setNativeBackPressEnabled({ enable: true });
Copy

setNativeBackPressHandler(callback: () => void): void

Registers a callback invoked when a native back press occurs (swipe, back button, etc.).

• Only effective when NativeBackPressEnabled = true.
• When a back press is triggered, the callback fires instead of the default WebView-back-or-dismiss behavior.
• If NativeBackPressEnabled = false, a warning is logged to the console and the handler will not fire.

const core = getHuaweiCore();

// Register a custom back press handler
core.setNativeBackPressHandler(() => {
  console.log('Back pressed — Web decides what to do');
  // e.g. navigate within SPA, show confirmation dialog, etc.
});
Copy

Geolocation

A drop-in replacement for @capacitor/geolocation when running inside HarmonyOS WebView.

Quick Start

import { isHuaWei, getHuaweiGeolocation } from 'aigens-sdk-huawei';
import { Geolocation as CapGeolocation } from '@capacitor/geolocation';

// Auto-detect environment and pick the right Geolocation
const Geo = isHuaWei() ? getHuaweiGeolocation() : CapGeolocation;

// One-shot position
const position = await Geo.getCurrentPosition();
console.log(position.coords.latitude, position.coords.longitude);

// Watch position
const watchId = await Geo.watchPosition({ enableHighAccuracy: true }, (pos, err) => {
  if (err) { console.error(err); return; }
  console.log('Update:', pos.coords.latitude, pos.coords.longitude);
});

// Stop watching
await Geo.clearWatch({ id: watchId });
Copy

getHuaweiGeolocation(): GeolocationPlugin

Returns a singleton GeolocationHuawei instance.

GeolocationPlugin Methods

All methods route through JS Bridge to HarmonyOS native (@kit.LocationKit).

getCurrentPosition(options?): Promise<Position>

Gets the current GPS position.

watchPosition(options, callback): Promise<CallbackID>

Starts continuous position updates. Native pushes updates via window.aigensGeolocationWatch(id, position).

clearWatch(options: { id }): Promise<void>

Stops a position watch.

checkPermissions(): Promise<PermissionStatus>

Checks location permission state. Returns { location, coarseLocation } where each is 'granted' / 'denied' / 'prompt'.

requestPermissions(): Promise<PermissionStatus>

Requests ohos.permission.LOCATION and ohos.permission.APPROXIMATELY_LOCATION from the user.

Types

interface Position {
  timestamp: number;
  coords: {
    latitude: number;
    longitude: number;
    accuracy: number;
    altitudeAccuracy: number | null | undefined;
    altitude: number | null;
    speed: number | null;
    heading: number | null;
  };
}

interface PositionOptions {
  enableHighAccuracy?: boolean;
  timeout?: number;       // ms
  maximumAge?: number;    // ms
}
Copy

Device

A drop-in replacement for @capacitor/device when running inside HarmonyOS WebView.

Quick Start

import { isHuaWei, getHuaweiDevice } from 'aigens-sdk-huawei';
import { Device as CapDevice } from '@capacitor/device';

// Auto-detect environment and pick the right Device
const Device = isHuaWei() ? getHuaweiDevice() : CapDevice;

const info = await Device.getInfo();
console.log(info.model, info.osVersion);

const battery = await Device.getBatteryInfo();
console.log(battery.batteryLevel, battery.isCharging);

const { uuid } = await Device.getId();
const { value: lang } = await Device.getLanguageCode();
Copy

getHuaweiDevice(): DevicePlugin

Returns a singleton DeviceHuawei instance.

DevicePlugin Methods

All methods route through JS Bridge to HarmonyOS native (deviceInfo, batteryInfo, i18n, statvfs).

getId(): Promise<DeviceId>

Returns a unique device identifier with a 3-tier fallback chain: deviceInfo.udid (system apps only) → identifier.getOAID() (device-level, stable across app reinstall; requires ohos.permission.ADVERTISING_INFO, ACL-enabled) → random UUID persisted via preferences (changes on reinstall).

interface DeviceId {
  uuid: string;
}
Copy

getInfo(): Promise<DeviceInfo>

Returns device/os/platform information from HarmonyOS deviceInfo and statvfs.

interface DeviceInfo {
  name?: string;            // deviceInfo.marketName
  model: string;            // deviceInfo.deviceModel
  platform: 'ios' | 'android' | 'web' | 'harmony';
  operatingSystem: OperatingSystem;
  osVersion: string;        // deviceInfo.osReleaseVersion
  manufacturer: string;     // deviceInfo.manufactureBrand
  isVirtual: boolean;
  memUsed?: number;
  diskFree?: number;
  diskTotal?: number;
  realDiskFree?: number;
  realDiskTotal?: number;
  webViewVersion: string;
}

type OperatingSystem = 'ios' | 'android' | 'windows' | 'mac' | 'unknown';
Copy

getBatteryInfo(): Promise<BatteryInfo>

Returns battery level (0–1) and charging state from HarmonyOS batteryInfo.

interface BatteryInfo {
  batteryLevel?: number;   // 0 to 1
  isCharging?: boolean;
}
Copy

getLanguageCode(): Promise<GetLanguageCodeResult>

Returns the system language locale code from HarmonyOS i18n.

interface GetLanguageCodeResult {
  value: string;
}
Copy

Preferences

A drop-in replacement for @capacitor/preferences when running inside HarmonyOS WebView.

Data is stored in HarmonyOS native preferences storage — persistent and not subject to the periodic localStorage clears the OS may perform on WebViews. Data is cleared when the app is uninstalled. No permissions required.

Quick Start

import { isHuaWei, getHuaweiPreferences } from 'aigens-sdk-huawei';
import { Preferences as CapPreferences } from '@capacitor/preferences';

// Auto-detect environment and pick the right Preferences
const Preferences = isHuaWei() ? getHuaweiPreferences() : CapPreferences;

await Preferences.set({ key: 'name', value: 'Max' });
const { value } = await Preferences.get({ key: 'name' }); // 'Max'
await Preferences.remove({ key: 'name' });
const { keys } = await Preferences.keys();
await Preferences.clear();
Copy

getHuaweiPreferences(): PreferencesPlugin

Returns a singleton PreferencesHuawei instance.

PreferencesPlugin Methods

All methods route through JS Bridge to HarmonyOS native preferences (ArkData).

Method	Notes
configure({ group })	group maps to the native preferences store name. Default: 'CapacitorStorage'.
get({ key })	Returns { value: string | null } — null when the key was never set or was removed.
set({ key, value })	String values only (use JSON.stringify for objects), then flushes to disk. Setting an empty value removes the key (cookie-like semantics — differs from @capacitor/preferences, which stores the empty string).
remove({ key })	Deletes the key.
clear()	Deletes all keys in the current group.
keys()	Returns { keys: string[] }.

Share

A drop-in replacement for @capacitor/share when running inside HarmonyOS WebView.

Opens the HarmonyOS system share panel (Share Kit). The promise resolves once the panel is presented; user completion is not awaited (same as Android). No permissions required.

Quick Start

import { isHuaWei, getHuaweiShare } from 'aigens-sdk-huawei';
import { Share as CapShare } from '@capacitor/share';

// Auto-detect environment and pick the right Share
const Share = isHuaWei() ? getHuaweiShare() : CapShare;

await Share.share({
  title: 'Check this out',
  text: 'Great coffee nearby',
  url: 'https://example.com',
});
Copy

getHuaweiShare(): SharePlugin

Returns a singleton ShareHuawei instance.

SharePlugin Methods

Method	Notes
canShare()	Always resolves { value: true } (system share panel is always available).
share({ title?, text?, url? })	Opens the system share panel. At least one of text / url is required. dialogTitle is ignored. activityType is always ''.

Camera

A drop-in replacement for @capacitor/camera when running inside HarmonyOS WebView.

Uses the HarmonyOS system pickers, which require no permissions:

• CAMERA source — secure system camera (cameraPicker)
• PHOTOS source — system gallery (PhotoViewPicker)
• PROMPT source (default) — an ActionSheet lets the user choose; labels are customizable via promptLabelHeader / promptLabelPhoto / promptLabelPicture

User cancellation rejects with Error('User cancelled'), matching Capacitor.

Quick Start

import { isHuaWei, getHuaweiCamera } from 'aigens-sdk-huawei';
import { Camera as CapCamera, CameraResultType } from '@capacitor/camera';

// Auto-detect environment and pick the right Camera
const Camera = isHuaWei() ? getHuaweiCamera() : CapCamera;

// Take a photo / pick from gallery, get a data URL
const photo = await Camera.getPhoto({
  resultType: CameraResultType.DataUrl,
  quality: 80,
});
imgElement.src = photo.dataUrl;

// Get a file path instead
const { webPath } = await Camera.getPhoto({
  resultType: CameraResultType.Uri,
});
imgElement.src = webPath;

// Pick multiple images
const { photos } = await Camera.pickImages({ limit: 5 });
Copy

getHuaweiCamera(): CameraPlugin

Returns a singleton CameraHuawei instance.

CameraPlugin Methods

Method	Notes
getPhoto(options)	resultType is required: 'uri' returns { path, webPath } (photo copied into the app cache dir; webPath is loadable by <img> inside the WebView), 'base64' / 'dataUrl' return a JPEG re-encoded with quality (default 100) and optional width / height (aspect ratio preserved). source defaults to 'PROMPT'; direction applies to 'CAMERA'. allowEditing / promptLabelCancel are accepted for @capacitor/camera drop-in compatibility but ignored (saved is always false).
pickImages(options?)	Multiple gallery pick; limit 0/undefined = system max (500). Returns { photos: [{ path, webPath, format }] } — URIs only, no base64 (avoids large memory overhead).
checkPermissions()	Always { camera: 'granted', photos: 'granted' } (system pickers need no permissions).
requestPermissions()	Same as checkPermissions() — a no-op.