Hi everyone,
I am working on a CarPlay integration, and need open a two level list opened from a root template. However, I am always receiving an error message when opening the 2nd pushed template.
To narrow it down not to have an issue with some app specific code I created the CarPlay scene below.
I am aware that there is a limit, but two levels I understand are supported on all CarPlay integrations, the maximum seems to be 5.
The app is just crashing right after showing the 2nd template.
Any ideas? Any hints are much appreciated.
Thanks a lot!
Regards, Michael
class CarPlaySceneDelegate2: UIResponder, CPTemplateApplicationSceneDelegate {
// [...]
private func createRootTemplate() -> CPListTemplate {
let pushToAItem = CPListItem(text: "Push to Template A", detailText: "Level 1 → Level 2")
pushToAItem.handler = {[weak self] (pushToAItem, completion) in
guard let self = self else {
completion()
return
}
self.interfaceController?.pushTemplate(
self.pushTemplateA(),
animated: true,
completion: { (didPresent, error) in
completion()
}
)
}
let section = CPListSection(items: [pushToAItem])
let template = CPListTemplate(title: "Root Template", sections: [section])
return template
}
private func pushTemplateA() -> CPListTemplate {
let pushToBItem = CPListItem(text: "Push to Template B", detailText: "Level 2 → Level 3")
pushToBItem.handler = {[weak self] (pushToBItem, completion) in
guard let self = self else {
completion()
return
}
self.interfaceController?.pushTemplate(
self.pushTemplateB(),
animated: true,
completion: { (didPresent, error) in
completion()
}
)
}
let backToRootItem = CPListItem(text: "Pop to Root", detailText: "Go back to root")
backToRootItem.handler = { [weak self] _, completion in
self?.interfaceController?.popToRootTemplate(animated: true, completion: nil)
completion();
}
let infoItem = CPListItem(text: "Current Depth", detailText: "2 (Template A)")
let stackCountItem = CPListItem(
text: "Stack Count",
detailText: "\((interfaceController?.templates.count ?? 0) + 1)"
)
let section = CPListSection(items: [pushToBItem, backToRootItem, infoItem, stackCountItem])
let template = CPListTemplate(title: "Template A", sections: [section])
return template
}
private func pushTemplateB() -> CPListTemplate {
let pushToCItem = CPListItem(text: "Push to Template C", detailText: "Level 3 → Level 4")
pushToCItem.handler = {[weak self] (pushToCItem, completion) in
guard let self = self else {
completion()
return
}
self.interfaceController?.pushTemplate(
self.pushTemplateC(),
animated: true,
completion: { (didPresent, error) in
completion()
}
)
}
let backToRootItem = CPListItem(text: "Pop to Root", detailText: "Go back to root")
backToRootItem.handler = { [weak self] _, completion in
self?.interfaceController?.popToRootTemplate(animated: true, completion: nil)
completion()
}
let popOneItem = CPListItem(text: "Pop One", detailText: "Go back to Template A")
popOneItem.handler = { [weak self] _, completion in
self?.interfaceController?.popTemplate(animated: true, completion: nil)
completion()
}
let infoItem = CPListItem(text: "Current Depth", detailText: "3 (Template B)")
let stackCountItem = CPListItem(
text: "Stack Count",
detailText: "\((interfaceController?.templates.count ?? 0) + 1)"
)
let section = CPListSection(items: [pushToCItem, popOneItem, backToRootItem, infoItem, stackCountItem])
let template = CPListTemplate(title: "Template B", sections: [section])
return template
}
private func pushTemplateC() -> CPListTemplate {
let backToRootItem = CPListItem(text: "Pop to Root", detailText: "Go back to root")
backToRootItem.handler = { [weak self] _, completion in
self?.interfaceController?.popToRootTemplate(animated: true, completion: nil)
completion()
}
let popOneItem = CPListItem(text: "Pop One", detailText: "Go back to Template B")
popOneItem.handler = { [weak self] _, completion in
self?.interfaceController?.popTemplate(animated: true, completion: nil)
completion()
}
let infoItem = CPListItem(text: "Current Depth", detailText: "4 (Template C)")
let stackCountItem = CPListItem(
text: "Stack Count",
detailText: "\((interfaceController?.templates.count ?? 0) + 1)"
)
let section = CPListSection(items: [popOneItem, backToRootItem, infoItem, stackCountItem])
let template = CPListTemplate(title: "Template C", sections: [section])
return template
}
}
I got an answer directly from Apple:
You've hit upon one of the most common and often confusing limitations in CarPlay development, the template stack depth limit. For most CarPlay apps, the navigation stack depth is limited to two templates. This means you can have a root template, and then push one more template on top of it. Attempting to push a third template will result in the "maximum level exception" you're seeing. Apple's first-party apps (like Music, Maps, Phone) often have special entitlements and UI paradigms that are not available to third-party developers, my apologies. Third-party apps that qualify for specific categories (e.g., audio, navigation, EV charging, parking, food ordering) can use
CPTabBarTemplate, but even then, each tab's stack is still limited to two. Yes, the crash reports and the "maximum level exception" are clear indicators of exceeding the template stack depth. This is not a bug in your code's logic, but rather a design constraint imposed by CarPlay for safety reasons. Since you cannot simply push more templates, you need to rethink your app's information architecture and navigation flow within the CarPlay constraints. The most common strategy is to update the content of an existing template rather than pushing a new one.
I was aware that there are some limits, however, we have a maximum of 2 and only for Apple's first-party apps some exceptions.
Lesson learned.
