zepp-os-app-control

name	zepp-os-app-control
description	Use when controlling the Zepp OS app itself — requesting/querying runtime permissions, reading package info, detecting the scene (normal/AOD), accessing live workout/sport data, adding a text keyboard, or building a Workout Extension or media app.
compatibility	Zepp OS Device App (Mini Program). Feature API_LEVEL varies — permissions/scene >=3.0, text keyboard >=3.6, Workout Extension / media app >=4.0-4.2. Declare permissions and app type in app.json.

Zepp OS App Control & Specialized Apps

Context: Device App (Mini Program). Prereq: declaring permissions in app.json + app types — see zepp-os-fundamentals.

Overview

@zos/app controls the running program: runtime permissions, package info, the current scene, performance. Beyond a normal app, Zepp OS has specialized targets (Workout Extension) and features (keyboard, media, live sport data).

Runtime permissions (@zos/app) [≥3.0]

Permissions are declared in app.json permissions[], but sensitive ones must also be requested at runtime:

import { queryPermission, requestPermission } from '@zos/app'

const [status] = queryPermission({ permissions: ['device:os.bg_service'] })
// if not granted:
requestPermission({
  permissions: ['device:os.bg_service'],
  callback: (result) => { /* result[] = granted status per permission */ },
})

Always queryPermission first, then requestPermission only if needed.

Other @zos/app controls

API	Use
getPackageInfo() / getPackageInfoById()	app id, name, version (e.g. for MessageBuilder appId)
getScene() + SCENE_*	detect normal vs AOD (see zepp-os-watchface)
getPerformance()	runtime performance data
emitCustomSystemEvent(...)	emit a custom system event

(App navigation — launchApp, home, exit — is in @zos/router, see zepp-os-navigation-lifecycle.)

Live workout data (@zos/app-access) [≥3.6]

getSportData({ type }, cb) reads live sport metrics (e.g. distance); permission data:user.hd.workout. The parsed object key can differ from the requested type (for example, docs list pace returning avg_pace), so check references/app-access.md.

import { getSportData } from '@zos/app-access'
getSportData({ type: 'distance' }, ({ code, data }) => {
  if (code === 0) { const [{ distance }] = JSON.parse(data) }
})

Specialized features (when to reach for a reference)

• System Keyboard [≥4.0] — on-watch text input via SYSTEM_KEYBOARD (see also widget.KEYBOARD [≥3.0] in zepp-os-ui).
• Custom Keyboard [≥4.2] — fully custom on-watch keyboard layout. See references/keyboard.md.
• Workout Extension [≥3.6] — a plug-in that extends the system Workout app (custom views/data during exercise). In app.json the type is "appType": "app" + "extType": "workout" + module.data-widget (not a distinct appType value). Scaffold with zeus create --appType WORKOUT_EXTENSION (CLI accepts WORKOUT_EXTENSION as a scaffold choice, but the generated app.json uses "appType": "app"). Introduced as a 3.5 feature, but requires minVersion 3.6 / device API_LEVEL ≥ 3.6. Device support is limited. See references/workout-extension.md.
• Media [≥3.0] — audio/media playback; player seek() is [≥4.2]. See references/media.md.

Common Mistakes

• Only declaring a permission in app.json → sensitive permissions also need a runtime requestPermission. Check with queryPermission first.
• Looking for exit/launchApp in @zos/app → app navigation is in @zos/router (zepp-os-navigation-lifecycle).
• Assuming Workout Extension runs everywhere → it needs [≥3.6] (minVersion 3.6) and only specific devices; it's not a separate appType value — it's "appType": "app" + "extType": "workout" in app.json.
• Forgetting data:user.hd.workout for getSportData.

Workout Extension setup

Progress:

• Scaffold: zeus create --appType WORKOUT_EXTENSION.
• app.json: set "appType": "app" + "extType": "workout", declare module.data-widget, set minVersion ≥ 3.6.
• Declare data:user.hd.workout permission (live sport data).
• Build the data-widget view(s); read live metrics via getSportData (@zos/app-access).
• Verify on a [≥3.6] device — support is limited. See references/workout-extension.md.

Reference

• references/app.md — @zos/app full API
• references/app-access.md — getSportData
• references/keyboard.md · workout-extension.md · media.md
• Signatures: npm @zeppos/device-types