@capgo/capacitor-auto

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

Install

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

What it does

• 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.

What it does not do

• 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.

Usage

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);
  }
});

Shared car state

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.

iOS setup

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>

Android setup

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.

Compatibility

API

isAvailable() => Promise<AutoAvailability>

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

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

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

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

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

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

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

getPluginVersion() => Promise<PluginVersionResult>

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

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

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

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

removeAllListeners() => Promise<void>