@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

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.*.* | v8.*.* | Yes |

API

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

isAvailable()

isAvailable() => Promise<AutoAvailability>

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

Returns: Promise<AutoAvailability>

setRootTemplate(...)

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

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

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | AutoTemplateOptions |

setState(...)

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.

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | AutoStateOptions |

getState(...)

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

Reads a persisted JSON state slice.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | AutoStateKeyOptions |

Returns: Promise<AutoStateResult>

removeState(...)

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

Removes a persisted JSON state slice.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | AutoStateKeyOptions |

setTransientState(...)

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

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

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | AutoStateOptions |

getTransientState(...)

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

Reads a process-local JSON state slice.

| Param | Type | | ------------- | ------------------------------------------------------------------- | | options | AutoStateKeyOptions |

Returns: Promise<AutoStateResult>

sendMessage(...)

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

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

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | AutoMessageOptions |

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns the platform implementation version marker.

Returns: Promise<PluginVersionResult>

addListener('connectionChanged', ...)

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

Fired when the car host connects or disconnects.

| Param | Type | | ------------------ | ----------------------------------------------------------------------------------------------------- | | eventName | 'connectionChanged' | | listenerFunc | (event: AutoConnectionChangedEvent) => void |

Returns: Promise<PluginListenerHandle>

addListener('carAction', ...)

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

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

| Param | Type | | ------------------ | ------------------------------------------------------------------------------- | | eventName | 'carAction' | | listenerFunc | (event: AutoActionEvent) => void |

Returns: Promise<PluginListenerHandle>

addListener('messageReceived', ...)

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

Fired for application-defined native car bridge messages.

| Param | Type | | ------------------ | --------------------------------------------------------------------------------- | | eventName | 'messageReceived' | | listenerFunc | (event: AutoMessageEvent) => void |

Returns: Promise<PluginListenerHandle>

addListener('stateChanged', ...)

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

Fired when a persisted or transient state value changes.

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------------- | | eventName | 'stateChanged' | | listenerFunc | (event: AutoStateChangedEvent) => void |

Returns: Promise<PluginListenerHandle>

removeAllListeners()

removeAllListeners() => Promise<void>

Interfaces

AutoAvailability

| Prop | Type | Description | | --------------- | ----------------------------------------------------- | ------------------------------------------------------------ | | available | boolean | Whether the current platform ships a native car integration. | | connected | boolean | Whether a car host is currently connected to this app. | | platform | AutoPlatform | Platform that answered the request. |

AutoTemplateOptions

| Prop | Type | Description | | --------------- | ---------------------------------- | ------------------------------------------- | | title | string | Title shown at the top of the car template. | | sections | AutoTemplateSection[] | Sections and rows to show in the car UI. | | emptyText | string | Text shown when there are no rows. |

AutoTemplateSection

| Prop | Type | Description | | ------------ | ------------------------------- | --------------------------------------------------------------------------------------- | | header | string | Optional section title. Supported by CarPlay; Android Auto currently flattens sections. | | items | AutoTemplateItem[] | Rows to render in this section. |

AutoTemplateItem

| Prop | Type | Description | Default | | -------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------- | | id | string | Stable action id sent back in the carAction event when the row is selected. | | | title | string | Primary row text. | | | subtitle | string | Optional secondary row text. | | | payload | AutoPayload | Optional value returned with the carAction event. | | | enabled | boolean | Whether the row can be selected. | true |

AutoPayload

AutoStateOptions

| Prop | Type | Description | | ----------- | --------------------------------------------------- | ------------------------------------------------- | | key | string | Application-defined state key. | | value | AutoPayload | JSON object to make available to native car code. |

AutoStateResult

| Prop | Type | Description | | ----------- | --------------------------------------------------- | ---------------------------------------------------------------------------- | | key | string | Application-defined state key. | | value | AutoPayload | Current JSON value for the requested key. Omitted when the key has no value. |

AutoStateKeyOptions

| Prop | Type | Description | | --------- | ------------------- | ------------------------------ | | key | string | Application-defined state key. |

AutoMessageOptions

| Prop | Type | Description | | ------------- | --------------------------------------------------- | ------------------------------------- | | type | string | Application-defined message type. | | payload | AutoPayload | Optional application-defined payload. |

PluginVersionResult

| Prop | Type | Description | | ------------- | ------------------- | ----------------------------------------------------------- | | version | string | Version identifier returned by the platform implementation. |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

AutoConnectionChangedEvent

| Prop | Type | | --------------- | ----------------------------------------------------- | | connected | boolean | | platform | AutoPlatform |

AutoActionEvent

| Prop | Type | | -------------- | ----------------------------------------------------- | | id | string | | title | string | | payload | AutoPayload | | platform | AutoPlatform |

AutoMessageEvent

| Prop | Type | | -------------- | ----------------------------------------------------- | | type | string | | payload | AutoPayload | | platform | AutoPlatform |

AutoStateChangedEvent

| Prop | Type | Description | | --------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------- | | key | string | Application-defined state key. | | value | AutoPayload | Current JSON value for the updated key. Omitted when the key has no value. | | platform | AutoPlatform | Platform that emitted the state update. | | transient | boolean | Whether the update came from transient in-memory state instead of persisted state. |

Type Aliases

AutoPlatform

'ios' | 'android' | 'web'