@capgo/capacitor-auto

Capacitor plugin for a small, template-safe bridge between your app and CarPlay / Android Auto.

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-auto` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-auto
npx cap sync

• Sends a simple list template from the phone app to the car display.
• Emits carAction events when the driver selects a car UI row.
• Emits connection events when the car host connects or disconnects.
• Persists a small JSON state slice that native car code can read when the Capacitor app is not running.
• Provides native entry points for CarPlay and Android Auto templated apps.

• It does not mirror a Capacitor WebView into the car display.
• It does not bypass Apple CarPlay entitlements, Google Play car app review, or driver-distraction template rules.
• It does not replace category-specific media, navigation, messaging, or calling APIs.

import { Auto } from '@capgo/capacitor-auto';

await Auto.setRootTemplate({
  title: 'Garage',
  sections: [
    {
      header: 'Doors',
      items: [
        {
          id: 'open-main-door',
          title: 'Open main door',
          subtitle: 'Tap to send the action to the phone app',
          payload: { doorId: 'main' },
        },
      ],
    },
  ],
});

await Auto.addListener('connectionChanged', (event) => {
  console.log('Car connected:', event.connected, event.platform);
});

await Auto.addListener('carAction', async (event) => {
  if (event.id === 'open-main-door') {
    await openGarageDoor(event.payload?.doorId);
  }
});

Android Auto and CarPlay can start without the Capacitor WebView. Keep the car experience independent by writing the state it needs into the plugin store whenever the phone app has fresh data.

await Auto.setState({
  key: 'navigation',
  value: {
    routeId: 'morning-commute',
    remainingDistanceMeters: 4200,
    instruction: 'Turn right in 300 meters',
  },
});

await Auto.addListener('stateChanged', (event) => {
  if (event.key === 'navigation') {
    console.log('Navigation state updated:', event.value);
  }
});

Native Android Auto or CarPlay code can read the same store directly through AutoStore.get(context) on Android and AutoStore.shared on iOS. The plugin also persists the last root template set with setRootTemplate, so a cold car session can render the most recent template before the web app wakes up.

CarPlay apps require Apple approval for the matching CarPlay entitlement and must use Apple-approved CarPlay templates for the app category.

Add a CarPlay scene configuration to the app Info.plist and point its delegate to the plugin scene delegate. The exact module prefix depends on how the plugin is integrated:

• Swift Package Manager target: AutoPlugin.AutoCarPlaySceneDelegate
• CocoaPods module: CapgoCapacitorAuto.AutoCarPlaySceneDelegate

<key>UIApplicationSceneManifest</key>
<dict>
  <key>UIApplicationSupportsMultipleScenes</key>
  <true/>
  <key>UISceneConfigurations</key>
  <dict>
    <key>CPTemplateApplicationSceneSessionRoleApplication</key>
    <array>
      <dict>
        <key>UISceneClassName</key>
        <string>CPTemplateApplicationScene</string>
        <key>UISceneDelegateClassName</key>
        <string>AutoPlugin.AutoCarPlaySceneDelegate</string>
      </dict>
    </array>
  </dict>
</dict>

The plugin includes an Android Auto CarAppService, declares the template capability, and defaults to the IOT car app category. Your app still has to qualify for the declared car category before publishing on Google Play.

If your app uses another category, override the service declaration in your app manifest and use the category Google requires for your use case.

• isAvailable()
• setRootTemplate(...)
• setState(...)
• getState(...)
• removeState(...)
• setTransientState(...)
• getTransientState(...)
• sendMessage(...)
• getPluginVersion()
• addListener('connectionChanged', ...)
• addListener('carAction', ...)
• addListener('messageReceived', ...)
• addListener('stateChanged', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

isAvailable() => Promise<AutoAvailability>

Returns whether the current platform supports this plugin and whether a car is connected.

Returns: Promise<AutoAvailability>

setRootTemplate(options: AutoTemplateOptions) => Promise<void>

Sets the root car template. Use this to push phone app state to the car display.

setState(options: AutoStateOptions) => Promise<void>

Persists a JSON state slice that native Android Auto and CarPlay code can read even when the Capacitor WebView is not alive.

getState(options: AutoStateKeyOptions) => Promise<AutoStateResult>

Reads a persisted JSON state slice.

Returns: Promise<AutoStateResult>

removeState(options: AutoStateKeyOptions) => Promise<void>

Removes a persisted JSON state slice.

setTransientState(options: AutoStateOptions) => Promise<void>

Stores a process-local JSON state slice and emits the same stateChanged event.

getTransientState(options: AutoStateKeyOptions) => Promise<AutoStateResult>

Reads a process-local JSON state slice.

Returns: Promise<AutoStateResult>

sendMessage(options: AutoMessageOptions) => Promise<void>

Sends an application-defined message to the native car bridge.

getPluginVersion() => Promise<PluginVersionResult>

Returns the platform implementation version marker.

Returns: Promise<PluginVersionResult>

addListener(eventName: 'connectionChanged', listenerFunc: (event: AutoConnectionChangedEvent) => void) => Promise<PluginListenerHandle>

Fired when the car host connects or disconnects.

Returns: Promise<PluginListenerHandle>

addListener(eventName: 'carAction', listenerFunc: (event: AutoActionEvent) => void) => Promise<PluginListenerHandle>

Fired when the user selects an action row in the car UI.

Returns: Promise<PluginListenerHandle>

addListener(eventName: 'messageReceived', listenerFunc: (event: AutoMessageEvent) => void) => Promise<PluginListenerHandle>

Fired for application-defined native car bridge messages.

Returns: Promise<PluginListenerHandle>

addListener(eventName: 'stateChanged', listenerFunc: (event: AutoStateChangedEvent) => void) => Promise<PluginListenerHandle>

Fired when a persisted or transient state value changes.

Returns: Promise<PluginListenerHandle>

removeAllListeners() => Promise<void>

'ios' | 'android' | 'web'