App | AIUI | Rokid

App is used to register an agent application.

App

App is used to register an agent application.

Define the App Lifecycle

export default {
  onLaunch(options) {
    // 智能体初始化
  },
  onShow(options) {
    // 智能体显示
  },
  onHide() {
    // 智能体隐藏
  },
  globalData: {
    // 全局数据
  }
}

Send a Message to the Host

The App instance can send structured data to the embedding AIUI host with postMessage():

export default {
  onLaunch() {
    this.postMessage(
      { type: 'app.ready' },
      { origin: 'aiui-agent', lastEventId: 'launch-1' },
    );
  },
};

Use the Agent Conversation

Use this.getAgent() in App methods, or getApp().getAgent() in Page scripts, to publish context and send messages or cards. See Agent Sessions for capability checks, acknowledgment semantics, and cleanup.

API Reference

getApp()

Returns the current App instance so pages or components can access app-level state and methods.

Session Access

app.getAgent()

Returns the current Agent session without creating a model or new conversation. Sessions may be unavailable or lack individual operations; see Agent Sessions.

app.environment

Independent, read-only public environment with theme, locale, display modes, safe-area insets, and a change event. It does not automatically publish model context or modify rendering and language settings. See Agent Sessions.

app.postMessage(data, options?)

Sends a JSON-compatible structured message to the host.

ParameterTypeRequiredDescription
dataanyYesJSON-compatible data to send.
options.originstringNoSender identifier. Defaults to 'ink-js'.
options.lastEventIdstringNoCorrelation identifier forwarded with the message.

Lifecycle Callbacks

The App lifecycle describes state changes for the entire agent application, from initialization through foreground entry and exit. Declare lifecycle callbacks on the object exported by app.js; each callback runs with the current App instance as this.

The App initializes, enters the foreground, and cycles between foreground and background

onLaunch() runs only once during initialization. The App can then move between foreground and background repeatedly through onShow() and onHide(). onError() is an independent error path rather than a foreground-state transition.

CallbackDescriptionTrigger Timing
onLaunchListens for agent initializationWhen agent initialization completes, only once globally
onShowListens for the agent being shownWhen the agent starts, or returns from background to foreground
onHideListens for the agent being hiddenWhen the agent moves from foreground to background
onErrorError listener functionWhen a script error occurs in the agent, or when an API call fails

onLaunch(Object options)

Runs once after the App finishes initializing. options contains the launch context. Use this callback to initialize globalData, restore persistent state, or establish app-level resources. Do not use it for work that depends on a page completing its initial render.

onShow(Object options)

Runs when the App is first shown and whenever it returns from the background. options contains the current show context. Use it to refresh app-level visibility state, resume paused work, or check whether data needs to be synchronized again.

onHide()

Runs when the App moves from the foreground to the background. Use it to pause foreground-only work, save temporary state, or release resources that do not need to remain active in the background. Moving to the background does not cause onLaunch() to run again.

onError(String msg)

Runs when the runtime reports an unhandled script error or API-call error. msg is the error message and can be recorded for diagnostics; this callback does not replace error handling provided by individual asynchronous APIs.

Event Callbacks

Host input events are delivered to the active Page or Widget first. They continue to the App only when propagation has not been stopped.

CallbackDescriptionTrigger Timing
onKeyDownListens for app-level key-down eventsWhen the user presses a key and the active page or Widget has not stopped propagation
onKeyUpListens for app-level key-up eventsWhen the user releases a key and the active page or Widget has not stopped propagation
onVoiceWakeupListens for app-level voice-wakeup eventsWhen voice wakeup is matched and the active page or Widget has not stopped propagation

onKeyDown(KeyboardEvent event)

Runs when the user presses a key. event.code identifies the key. The App receives this event after the active Page or Widget, so use it for app-wide shortcuts whose propagation was not stopped by the active entry surface.

onKeyUp(KeyboardEvent event)

Runs when the user releases a key. event.code identifies the key. Some keys have default behavior such as navigating back, scrolling, or activating a target after event dispatch; call event.preventDefault() to prevent that behavior.

onVoiceWakeup(VoiceWakeupEvent event)

Runs after the host detects voice wakeup. event.keyword contains the matched wake word. This event also passes through the active Page or Widget first, so use the App callback for voice-wakeup handling shared across pages.

onNetworkStatus(event)

Runs when network status changes. event.online is a boolean; event.status is 'online' or 'offline'. Read connection type and quality from navigator.connection. Online status does not guarantee request success.