CarPlay — entitlements, template scene, limits

ios-platform · folio

In one line: A CarPlay app is not a separate target: it is a second scene (CPTemplateApplicationScene) of your iOS app, same process. You never draw its UI — you hand templates to a CPInterfaceController and the car renders them. Apple grants one category entitlement; the category decides which templates you may use and how deep the stack goes. Only navigation apps draw pixels (the map, in a CPWindow).

Download PDF Print view LaTeX source

CarPlay — entitlements, template scene, limits — figure 1

How it works

  • Entitlement per category, requested from Apple; a Boolean key in .entitlements, matching App ID + profile. A template outside your category → runtime exception.
  • Scene manifest: UISceneConfigurations gets a CPTemplateApplicationSceneSessionRoleApplication entry (class CPTemplateApplicationScene + your delegate). No extension, no new target.
  • Connect: templateApplicationScene(_:didConnect:) hands you the CPInterfaceController: keep it, setRootTemplate. Nav apps get …didConnect:to: with a CPWindow. Disconnect → drop both.
  • Stack: push / pop / pop(to:); presentTemplate shows one modal. CPTabBarTemplate is root only, each tab its own stack.
  • Templates are data: text, CPImageSet (light/dark), handlers. Update in place (updateSections(_:)).
  • The car sets limits: maximumItemCount, maximumTabCount, CPSessionConfiguration.limitedUserInterfaces (.keyboard, .lists while driving); a grid shows 8 buttons.

Categories — key com.apple.developer.carplay-…

categorykey suffixdepthown templates · rule
audioaudio5Now Playing
communicationcommunication5Contact
navigationmaps5Map, Search, Voice
EV charging, parkingcharging, parking5Point of Interest, Information
quick food orderingquick-ordering2 (3†)Point of Interest, Information
fueling (iOS 16)—3
driving task (iOS 16)driving-task2 (3†)
public safety——dispatch, routing
voice conv. (26.4)voice-based-
conversation(unverified)
3audio session only while voice is in use
video (iOS 27)——parked only, AirPlay video
† iOS 26.4+. List, grid, tab, alert, action sheet: all. Information: not audio. EV + fueling combine, audio + video too. Old MPPlayableContentManager: deprecated (14).

Example — audio app, scene delegate

func templateApplicationScene(_ s: CPTemplateApplicationScene,
                didConnect ui: CPInterfaceController) {
  self.ui = ui                              // keep it
  let max = CPListTemplate.maximumItemCount // the car's limit
  let rows = Library.shared.albums.prefix(max).map { a in
    let row = CPListItem(text: a.title, detailText: a.artist)
    row.handler = { _, done in
      Player.shared.play(a)                 // shared model
      ui.pushTemplate(CPNowPlayingTemplate.shared,
                      animated: true, completion: nil)
      done() }                              // or it spins forever
    return row }
  let list = CPListTemplate(title: "Albums",
                 sections: [CPListSection(items: rows)])
  ui.setRootTemplate(list, animated: true, completion: nil)
}

Testing

Xcode Simulator I/O → External Displays → CarPlay (800×480 @2x): no locked iPhone, Siri or audio. CarPlay Simulator (Mac app, Additional Tools for Xcode) drives a real iPhone over a cable.

Traps

  • Model built in the phone SceneDelegate: CarPlay may launch you with no phone scene.
  • Locked phone: .complete files and WhenUnlocked keychain items fail — use completeUntilFirstUserAuthentication / AfterFirstUnlock.
  • Hard-coded row counts: read the limits at runtime; they shrink while driving.
  • “Custom CarPlay UI”: only the nav map. No video (bar parked video apps), games or free text.

Per category

  • Audio: browse → CPNowPlayingTemplate.shared, a singleton fed by MPNowPlayingInfoCenter; its buttons and the steering wheel go through MPRemoteCommandCenter — the lock-screen plumbing.
  • Communication: SiriKit (INSendMessageIntent, INSearchForMessagesIntent, INStartCallIntent) + CallKit; CPContactTemplate, CPMessageListItem. Siri dictates — no keyboard.
  • Navigation: CPMapTemplate (buttons, trips, maneuvers via CPNavigationSession) over your map; CPSearchTemplate; Dashboard (CPSupportsDashboardNavigationScene) + instrument-cluster scenes.
  • EV / parking / food: CPPointOfInterestTemplate (map + picker), CPInformationTemplate (items + ≤ 3 CPTextButtons).

New in iOS 26 · 26.4 · 27

  • 26: .systemSmall widgets + Live Activities (.small) show on the Dashboard, no CarPlay app needed; opt out: .disfavoredLocations([.carPlay], for: [.systemSmall]).
  • 26.4: voice conversational apps; food/driving-task depth 3.
  • 27: video apps — parked, in cars with video-in-car; AirPlay video; audio-only fallback (supportsVideoPlayback). CPVoiceControlTemplate for all.
  • CarPlay Ultra (every car display): automaker feature; templates restyle.

Remember

“The entitlement picks the templates, templates are data, the car draws — only maps get pixels.”

Report a problem ·Discuss this folio