Skip to content

CarPlay templates and actions

The debug SDK serves GET /carplay/templates and POST /carplay/action. Identity authorization still applies, but phone foreground state does not: CarPlay can remain active while the phone app is backgrounded. The walk, actions and registration run on the main thread using public CarPlay APIs only.

Apps opt in with AutoMobileSDK.shared.registerCarPlay(interfaceController:) and disconnect with unregisterCarPlay(). The controller is weakly held. Before registration the snapshot route returns schemaVersion 1, enabled false, connected false, empty templates and truncated false, without initializing CarPlay. After registration, enabled remains true; connected reflects whether the controller is still alive, including after unregister.

Templates follow the controller stack bottom to top, with an optional presented node. Slash paths identify stack indices, sections/items, buttons, tabs and nested tab templates. Image-row elements use items/N/buttons/M; information and alert actions use actions/N. Navigation buttons use leadingNavigationBarButtons/N, trailingNavigationBarButtons/N and backButton/0. Navigation bar buttons are read for list, grid, information, point-of-interest, map, contact and voice-control templates; other templates omit them. IDs describe positions in each snapshot, not identities across stack changes. Lists expose text, detail text, enabled and image presence; grids expose title variants and enabled; tabs expose selection and nested templates. Information items and text actions, navigation bar buttons, alert titles/actions and action-sheet titles, messages and actions use public properties. Other known template families report their type; unknown templates include className. Images are never serialized, and these objects describe app templates rather than host-rendered pixels.

The mapper caps each collection at 50, all nodes at 500, and depth at 6 (root depth zero). Sections, rows, tab wrappers and actions count toward the node budget. Any omitted nodes set truncated true. Optional values are omitted from JSON. The Codable model and disabled path compile without CarPlay; mapper tests require an iOS simulator destination through xcodebuild. CarPlayFixture provides fixed templates independently of Playground.

POST /carplay/action takes { "id": "<snapshot id>", "action": "select" }. Omitted action defaults to select; back and popToRoot need no id. Malformed JSON, unknown actions and selection without a nonempty id return HTTP 400 bad_request. Valid requests return HTTP 200 with { schemaVersion: 1, status, simulated: "sdk", action, templates }, optional id and optional reason. Here templates is the complete snapshot document taken after the callback returns or the controller’s pop completion runs. Later asynchronous app work may require another snapshot.

Selection re-walks the live templates with the mapper’s same IDs and budgets. List rows, image-row elements and alert actions invoke their public handlers; list callbacks receive a no-op completion. Tab IDs select that tab. Navigation uses nonanimated controller pop operations and reports completion errors as failed. Missing IDs return not_found; disabled elements and missing list handlers return failed. IDs of nodes without a public selection API return unsupported. Grid, bar and text buttons expose their handlers only through initializers, so the SDK cannot invoke them using public API and returns unsupported (disabled grid/bar buttons still return failed).

Before opt-in or without a connected controller, actions return unsupported with a reason and the current snapshot. Both routes bypass only the phone foreground gate; neither dispatches phone-screen interactions. Registration remains DEBUG-only. No MCP tool or runner action dispatch is provided by these SDK routes.