Skip to content

Background operation and lifecycle

Phone screen locking, backgrounding, and page recreation can affect plugins. Do not assume a Web page remains active.

Handling state in Web pages#

  • Receive host-state changes with gm.on("runtime.lifecycleChanged", handler), and query the current state with gm.runtime.getLifecycleState().
  • On entering suspended, stop unnecessary UI updates, location watches, network tasks, and similar work. Recheck resources and connections after resuming.
  • After page recreation, call gm.ready() again and request the needed subscriptions. Do not cache or reuse old-session tokens, requests, or file streams.
  • Call the unsubscribe function returned by event-listener registration when the feature ends.

Audio behavior depends on the API#

The current App preserves a dedicated path for active recording during screen lock, while ordinary Web pages suspend sensitive resources. This does not guarantee that arbitrary plugins can run indefinitely in the background. Verify your recording, file, network, and location scenarios against system restrictions.

Test at least these scenarios#

  1. Open plugin, start core operations, lock screen and unlock.
  2. Switch to another App and return. Check for duplicate subscriptions and old replies overwriting new state.
  3. Test backgrounding both during and outside recording, then confirm that stop and exit release resources.
  4. Disconnect and reconnect the glasses, checking prompts and recovery. Let the user restart the plugin if necessary.

Reference files in the toolkit#

  • PhoneSDK/docs/web-plugin/runtime-and-lifecycle.md
  • PhoneSDK/examples/permission-debug/plugin.js