Cordova / Capacitor Setup

Add the Capacitor bridge to a development build, initialize it from app bootstrap, and verify the first connection.

Use this guide for Capacitor 8 apps. Classic Apache Cordova is not currently a drop-in target for @ansight/capacitor.

1. Add and sync the package

npm install @ansight/capacitor
npx cap sync

The package links ai.ansight:ansight-android on Android and the Ansight package/pod on iOS.

2. Initialize the development build

import Ansight from "@ansight/capacitor";

export async function startAnsight(isDevelopmentBuild: boolean): Promise<void> {
  if (!isDevelopmentBuild) {
    return;
  }

  await Ansight.initializeAndActivate(
    Ansight.createOptionsBuilder()
      .withAnsightDefaults()
      .withReadOnlyToolAccess()
      .withDomTools()
      .withErrorCapture()
      .build(),
  );
}

Call startAnsight(...) once the Capacitor runtime and document are available, passing the application’s existing development-variant flag. Do not replace it with a hard-coded true. initializeAndActivate(...) also starts lifecycle tracking unless lifecycle: false is supplied.

3. Add stable DOM ids

Give important elements stable id or supported test attributes so the DOM tree remains easy for developers and agents to query:

<button id="login-button" type="submit">Sign in</button>

4. Run and verify

Start the host in one terminal, then launch the native development build from your IDE or normal Capacitor workflow:

ansight host run

From another terminal, confirm the connected session and tool catalog:

ansight session list --connected --json
ansight app tools <session-id> --json

A physical device requires the one-time enrollment flow.

Platform requirements

  • Capacitor 8 (@capacitor/core >=8.0.0 <9.0.0).
  • Android: API 24 or newer and Java 21.
  • iOS/iPadOS: deployment target 15.0 or newer.
  • iOS/iPadOS: add NSLocalNetworkUsageDescription when a physical device connects to the local Ansight host over the LAN.
<key>NSLocalNetworkUsageDescription</key>
<string>Connect to the Ansight developer host on the local network.</string>

After configuration changes, run npx cap sync and build both native projects.

Troubleshooting

  • The native module is missing: rerun npx cap sync and rebuild the native development app rather than refreshing only the web bundle.
  • DOM tools are missing: confirm .withDomTools() remains in the guarded development options and initialization runs after the document is available.
  • No connected session: confirm the host is running and the value passed to startAnsight(...) is true only for the intended development variant.