/carplay

name: carplay
description: "Build CarPlay-enabled apps using the CarPlay framework. Use when creating navigation, audio, communication, EV charging, parking, or food ordering apps for the car display, working with CPTemplateApplicationScene, CPInterfaceController template hierarchies, CPListTemplate, CPMapTemplate, CPNowPlayingTemplate, configuring CarPlay entitlements, or integrating with CarPlay Simulator for testing."

CarPlay

Build category-entitled, template-based CarPlay apps for the vehicle display. Scope: Swift 6.3, iOS 26+.

See [references/carplay-patterns.md](references/carplay-patterns.md) for extended patterns including full navigation sessions, dashboard scenes, and advanced template composition.

Scope boundary: full CarPlay framework apps use category entitlements, `CPTemplateApplicationScene`, `CPTemplateApplicationSceneDelegate`, `CPInterfaceController`, and system `CPTemplate` navigation. CarPlay-visible WidgetKit widgets and ActivityKit Live Activities are separate system experiences; route their implementation to those domains while keeping CarPlay-specific validation here.

Contents

• [Entitlements and Setup](#entitlements-and-setup)
• [Scene Configuration](#scene-configuration)
• [Templates Overview](#templates-overview)
• [Navigation Apps](#navigation-apps)
• [Audio Apps](#audio-apps)
• [Communication Apps](#communication-apps)
• [Point of Interest Apps](#point-of-interest-apps)
• [Testing with CarPlay Simulator](#testing-with-carplay-simulator)
• [Common Mistakes](#common-mistakes)
• [Review Checklist](#review-checklist)
• [References](#references)

Entitlements and Setup

Request the category-specific entitlement from [Apple's CarPlay entitlement form](https://developer.apple.com/contact/carplay), accept the addendum, then provision the approved category key below.

Entitlement Keys by Category

| Entitlement | Category | |---|---| | `com.apple.developer.carplay-audio` | Audio | | `com.apple.developer.carplay-communication` | Communication | | `com.apple.developer.carplay-maps` | Navigation | | `com.apple.developer.carplay-charging` | EV Charging | | `com.apple.developer.carplay-parking` | Parking | | `com.apple.developer.carplay-quick-ordering` | Quick Food Ordering |

Project Configuration

1. Update the App ID in the developer portal under Additional Capabilities. 2. Generate a new provisioning profile for the updated App ID. 3. In Xcode, disable automatic signing and import the CarPlay provisioning profile. 4. Add an `Entitlements.plist` with the entitlement key set to `true`. 5. Set Code Signing Entitlements build setting to the `Entitlements.plist` path.

Key Types

| Type | Role | |---|---| | `CPTemplateApplicationScene` | UIScene subclass for the CarPlay display | | `CPTemplateApplicationSceneDelegate` | Scene connect/disconnect lifecycle | | `CPInterfaceController` | CarPlay-provided controller for setting the root template and pushing, presenting, or popping templates | | `CPTemplate` | Abstract base for all CarPlay templates | | `CPSessionConfiguration` | Vehicle display limits and content style |

Scene Configuration

Declare the CarPlay scene in `Info.plist` and implement `CPTemplateApplicationSceneDelegate` to respond when CarPlay connects.

Info.plist Scene Manifest

<key>UIApplicationSceneManifest</key>
<dict>
    <key>UIApplicationSupportsMultipleScenes</key>
    <true/>
    <key>UISceneConfigurations</key>
    <dict>
        <key>CPTemplateApplicationSceneSessionRoleApplication</key>
        <array>
            <dict>
                <key>UISceneClassName</key>
                <string>CPTemplateApplicationScene</string>
                <key>UISceneConfigurationName</key>
                <string>CarPlaySceneConfiguration</string>
                <key>UISceneDelegateClassName</key>
                <string>$(PRODUCT_MODULE_NAME).CarPlaySceneDelegate</string>
            </dict>
        </array>
    </dict>
</dict>

Scene Delegate (Non-Navigation)

Non-navigation apps receive an interface controller only. No window.

import CarPlay

final class CarPlaySceneDelegate: UIResponder,
    CPTemplateApplicationSceneDelegate {

    var interfaceController: CPInterfaceController?

    func templateApplicationScene(
        _ templateApplicationScene: CPTemplateApplicationScene,
        didConnect interfaceController: CPInterfaceController
    ) {
        self.interfaceController = interfaceController
        interfaceController.setRootTemplate(buildRootTemplate(),
                                            animated: true, completion: nil)
    }

    func templateApplicationScene(
        _ templateApplicationScene: CPTemplateApplicationScene,
        didDisconnectInterfaceController interfaceController: CPInterfaceController
    ) {
        self.interfaceController = nil
    }
}

Scene Delegate (Navigation)

Navigation apps receive both an interface controller and a `CPWindow`. Set the window's root view controller to draw map content.

func templateApplicationScene(
    _ templateApplicationScene: CPTemplateApplicationScene,
    didConnect interfaceController: CPInterfaceController,
    to window: CPWindow
) {
    self.interfaceController = interfaceController
    self.carWindow = window
    window.rootViewController = MapViewController()

    let mapTemplate = CPMapTemplate()
    mapTemplate.mapDelegate = self
    interfaceController.setRootTemplate(mapTemplate, animated: true,
                                        completion: nil)
}

Templates Overview

CarPlay provides a fixed set of template types. The app supplies content; the system renders it on the vehicle display.

General Purpose Templates

| Template | Purpose | |---|---| | `CPTabBarTemplate` | Container with tabbed child templates | | `CPListTemplate` | Scrollable sectioned list | | `CPGridTemplate` | Grid of tappable icon buttons (max 8) | | `CPInformationTemplate` | Key-value info with up to 3 action