Record apps without adding an SDK

External monitoring records an installed app while it is running. It discovers iOS simulators and Android emulators automatically and follows their app processes. An exact physical iPhone can be monitored using Appium/XCUITest, and an exact physical Android phone can be monitored using ADB. Physical-device recordings follow the app while it is in the foreground. No Ansight SDK or pairing QR is required in the target app.

The resident host discovers booted virtual devices, including devices booted after monitoring starts. Each matching device gets a separate session. The monitor does not boot devices or install the app for you. Physical-device monitoring requires an explicit device ID and platform.

Set up monitoring in the local player

1. Install the app on a simulator, emulator, or physical phone. Run ansight doctor to check the required platform tools; iOS Simulator requires macOS and Xcode.
2. Start the host with ansight host run --open and leave it running.
3. Open Apps, then the Monitoring tab.
4. Enter the app’s bundle or package identifier under Monitor an app. Optionally restrict the platform to iOS or Android. For a physical phone, select its platform and enter its exact ID from ansight device list --physical.
5. Select Monitor app, then launch the app on the selected device.
6. Check Monitored apps for the device, capture state, and session ID. Open that session to review the incoming recording.

Use Search apps in the Apps list to find a registered app by name or package identifier. An app’s Monitor app action opens the monitoring form with its ID filled in. The monitored-app list has its own search.

Monitoring settings survive host restarts. Disable ends active captures and keeps the monitor definition; Remove monitor ends them and removes the definition. Both keep the recorded sessions.

Each monitor has its own Screenshot interval (seconds). Set it when adding the monitor, or edit the value under Monitored apps and select Save interval. The default is 2 seconds; set 1 for a target of one screenshot per second. Values from 0.1 to 60 seconds are supported. Changes apply to active recordings without restarting them and are saved across host restarts. Capture is sequential, so device speed can limit the actual frequency.

From the CLI, pass --screenshot-interval-ms 1000 when adding a monitor, or update an existing one while preserving its other settings:

ansight app watch configure <watch-id> --screenshot-interval-ms 1000

On a physical phone, backgrounding the app ends its recording after two observations, even if the process remains alive. Virtual-device recordings continue while the process runs. A process restart creates a new session. Only one capture can own a device at a time. The monitor reports when another capture or execution has reserved it. Recording starts also use the host’s recording notification flow, subject to notification preferences and operating-system permissions. Physical-phone recordings retain lifecycle.foreground and lifecycle.background timeline markers using the same app-state display as SDK sessions. Markers use the time the host observes the transition, before recording-stop confirmation or Instruments export. Repeated observations do not add duplicate markers; failed probes and process disappearance alone do not establish a lifecycle state. Virtual-device screenshots reflect the device display, so they can show another app while the watched app remains in the background.

Physical iPhone monitors share one Appium connection per device. If that connection expires, foreground, screenshot, and accessibility reads recreate it and retry once without launching the app. Failed captures release the device so monitoring can reconnect while the app remains open.

Set up monitoring from the CLI

Monitor an App ID across both platforms:

ansight app watch add com.example.notes
ansight app watch list --json

To restrict a monitor and save a file when its capture ends:

ansight app watch add com.example.notes --platform ios \
  --capture-file Documents/notes.sqlite

ansight app watch add com.example.notes --platform android \
  --capture-file files/notes.sqlite

To monitor an installed app on a physical Android phone, enable USB debugging, authorize the host computer, and confirm adb devices lists the phone as device. Use its exact ADB serial:

ansight app watch add com.example.notes --platform android \
  --device-id <adb-serial>
ansight app watch list --json

Bring the app to the foreground. The watch records screenshots, accessibility UI, Logcat, and available process telemetry through ADB. It does not require Appium. Backgrounding ends the recording. Private sandbox files are available only when run-as works for a debuggable build or an already provisioned root ADB daemon is present.

To monitor a physical iPhone with a non-debug App Store app, install Appium and its XCUITest driver, then start the Appium server. Pair and trust the unlocked phone and enable Developer Mode and UI Automation. WebDriverAgent must be signed for that phone; see WebDriverAgent signing and distribution. Set the signing variables before starting the Ansight host, then run:

ansight device list --physical
ansight app watch add com.example.notes --platform ios \
  --device-id <coredevice-id> --instruments
ansight app watch list --json

Bring the app to the foreground, then use ansight session list --connected --json or the active session ID in app watch list --json to open the capture. Backgrounding the app or stopping its process ends the physical-iPhone watch.

The optional --instruments flag records Xcode’s Activity Monitor template across the selected iPhone for up to ten minutes. Ansight imports only the watched app’s PID into its CPU and memory telemetry. Device-wide recording supports store apps that Instruments cannot attach to directly. When the watch ends, Ansight automatically exports and ingests telemetry, then saves a capture.trace.zip artifact with capture timing and export metadata in the same session. This option requires an explicitly selected physical iPhone and does not relaunch the app. The native trace can be opened in Instruments after extraction. While Instruments is recording, the empty telemetry timeline explains that telemetry is being captured and will appear automatically after the session ends. The message changes to processing during export and disappears when samples arrive. Capture failures and traces without samples show their own status instead. The telemetry chart shows the current processing stage, progress through five stages, and elapsed time inline. When processing finishes, the progress message disappears and the chart shows the samples. Failures report the error inline. Stage progress describes work completed rather than estimating how long the remaining export will take. Ansight attempts to export the table of contents and process samples. If Instruments cannot export the derived Activity Monitor table, Ansight uses its raw process counters for CPU, physical footprint, and resident memory. The exported samples remain in the session alongside the trace. If both exports fail, the trace remains in the session and the host retries metric recovery from that archive when the capture ends or the host starts again. When the process table exports successfully, Ansight adds CPU, physical footprint, and real memory channels to the telemetry chart. An Instruments recording startup failure leaves no trace to recover; the session still keeps its other external evidence.

Appium defaults to http://127.0.0.1:4723; set ANSIGHT_APPIUM_SERVER_URL when it listens elsewhere. The watch waits for the app’s foreground process and starts WebDriverAgent without automatically launching or terminating the target app. Keep the phone unlocked for reliable screenshots and accessibility snapshots. The initial Appium setup can take longer than a simulator capture. No IPA extraction is required.

WebDriverAgent signing and distribution

Appium uses WebDriverAgent (WDA) to automate a physical iPhone. For the usual setup, install the XCUITest driver and leave the Appium server running:

npm install --global appium
appium driver install xcuitest
appium

In the Ansight host’s environment, set ANSIGHT_APPIUM_XCODE_TEAM_ID or ANSIGHT_APPIUM_XCODE_CONFIG_FILE for an xcconfig file. Set ANSIGHT_APPIUM_WDA_BUNDLE_ID if your provisioning profile requires a different WDA identifier, and ANSIGHT_APPIUM_XCODE_SIGNING_ID if the default Apple Development identity is unsuitable. Start or restart the host after setting these values. For example, in a second terminal:

export ANSIGHT_APPIUM_XCODE_TEAM_ID=YOUR_APPLE_TEAM_ID
ansight doctor
ansight host run --open

Doctor checks the Appium executable, driver, and server. It does not prove that WDA can be signed and launched until a device session starts.

An arbitrary self-signed certificate cannot authorize a WDA bundle on iOS. Use an Apple developer signing identity and a provisioning profile that covers the WDA bundle ID and each target device. A signed WDA bundle can be reused or distributed to devices covered by that profile; other devices need suitable provisioning. See Apple’s provisioning explanation and Appium’s real-device setup.

Appium supports a preinstalled WDA through usePreinstalledWDA and an optional prebuiltWDAPath on supported iOS and driver versions. Ansight’s physical-iOS client currently exposes signing settings, but does not set those preinstalled WDA capabilities; it uses Appium’s normal WDA startup path. See Appium’s preinstalled WDA guide for that separate workflow.

Use --device-id for one iOS device ID, Android serial, or AVD name. Omitting it enables automatic virtual-device discovery. Re-adding the same app/platform/device selection updates and enables its monitor.

Copy the monitor ID from app watch list to manage it:

ansight app watch disable <watch-id>
ansight app watch enable <watch-id>
ansight app watch remove <watch-id>

See the app-watch command reference for options.

What external capture includes

Availability depends on platform tools and permissions. The session properties and properties window identify SDK versus external capture and retain provider and capability details.

CPU is recorded in millicores: 1,000 means one fully utilized logical CPU. Memory is recorded in bytes. Android renderer FPS measures frames produced during the sample interval; a static screen can report zero. Missing or unsupported frame statistics are reported as unavailable. iOS simulator FPS is not inferred from screenshot frequency. See Telemetry Review.

Expand capture with the SDK

Add the Ansight SDK to capture touch inputs and gestures, instrumented network requests, custom telemetry and events, and app-internal or framework tools. These depend on the SDK features enabled in the app. External UI automation can send inputs, but it does not record a user’s touches for replay. The player provides SDK setup guidance on features that need this integration. The same limit applies to touches made directly on a physical iPhone while WDA is running. Automation commands sent by Ansight are separate from captured user touch events.

Browse and retain sandbox files

Open Files on a live external session to browse, preview, download, or save files to the timeline. iOS access uses the simulator’s containers. Android private-file access requires a debuggable app supporting run-as, or a root ADB daemon that is already configured. Capture can still work when private files are unavailable. See Live Files and Viewers.

For automatic copies, expand Save sandbox files when capture ends in the monitor form and enter one data-sandbox-relative path per line. The CLI’s --capture-file option is repeatable. Each monitor supports up to 16 files, at most 16 MiB each. Copies are attempted on process exit, monitor disable or removal, and host shutdown. They are skipped on an observed process restart or device loss to avoid attaching files from a different run.

These are best-effort copies. A changing SQLite database may require its WAL files or an app-provided consistent snapshot. The sandbox-capture artifact’s capture.json records the source path, provider, size, checksum, timestamps, and copy consistency; it is metadata written by Ansight. Watch exit copies do not require a workspace trigger.

Link a workspace and run automation

App metadata registration, app monitoring, and workspace linking have separate purposes. To create and register a workspace for this App ID:

ansight workspace init /path/to/workspace --app-id com.example.notes

This links the trusted repository, connects its automation, and enables automatic Trends evaluation for finalized sessions. An existing workspace can also be linked in the app’s Workspace path field; use Connect automations when its triggers are disconnected. Registering an App ID alone does not create a monitor.

Use the monitor’s active session for a prompt or a saved workspace test:

ansight app execute <live-session-id> \
  --prompt "Create a note and verify it appears in the list"

ansight test run /path/to/workspace notes.smoke \
  --session-id <live-session-id>

The session determines execution mode. One execution reserves it at a time; releasing the reservation leaves the monitor running. To launch an installed app without an existing session, select device mode explicitly:

ansight app execute --app-id com.example.notes --platform ios \
  --device-id <simulator-udid> --execution-mode device \
  --prompt "Create a note and verify it appears in the list"

• Tests use visible UI and captured evidence, with simulator .app or emulator .apk builds.
• Tasks use schema version 2, declare their requirements, and check capabilities before using optional features. App-tool calls require a connected SDK provider.
• Triggers can match native logs and return a host screenshot, file capture, or annotation action.
• Trends can use native log messages as span boundaries and measure available external telemetry. Provider metadata keeps incompatible measurements out of the same baseline.

If recording does not start

Check ansight app watch list --json for per-device state and errors. Confirm the resident host is running, the virtual device is booted, the exact App ID is installed, and its process is running. A home-screen icon alone does not mean the process is alive. Resolve device reservation conflicts before retrying. For missing files or metrics, inspect that session’s capability details and run ansight doctor for platform dependency diagnostics.