Cordova / Capacitor Setup

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

Open your app repository in your coding agent and send:

Copyable prompt:

Use https://www.ansight.ai/skills/cordova/ansight-install-cordova.md to install Ansight in this Capacitor app. Keep it in a development build, verify a connected session, and show me the changes.

The Capacitor installation skill handles the native bridge and checks the integration. The steps below are the manual reference.

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@latest
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> --detail summary --include-unavailable --max-results 50 --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.