When developing an app for Apple CarPlay there is not much good documentation online apart from the official Apple documentation. After developing a CarPlay audio app for a large media company I want to share some lessons or insights that we learned along the way that are not that easy to find in the official documentation.
CarPlay apps can be categorized into six different types:: Audio, Communication, EV Charging, Navigation, Parking and Quick Food Ordering. The primary difference between these categories lies in the components that developers can utilize in their apps. However, this article will focus solely on the development of a CarPlay audio app. Please note that the insights shared in this article are based on iOS versions 15 through 17.5.
CarPlay simulator
There are different methods available for testing a CarPlay application. The most direct approach is to use the app in an actual car with an iPhone, providing a real-world testing environment. However, this may not always be practical. A viable alternative is to buy a portable CarPlay radio for desktop testing. Both of these options offer the benefit of replicating authentic CarPlay conditions, such as having a touch display, as opposed to utilizing CarPlay with a mouse or trackpad.
As for simulators, Xcode’s standard iPhone simulator has a built-in CarPlay Simulator accessible via “I/O -> External Displays -> CarPlay…“. Although convenient, it lacks some real hardware functionalities like the touch display or physical scroll wheel. Some components behave differently than they would in an actual car. For example, the play/pause button in the fullscreen player doesn’t accurately reflect the playback state (see screenshot). It seems like the song is paused even though it is playing. On the other side, it is convenient as no extra device is needed and for some use cases like checking if certain list items are displayed, it is acceptable.
Apple offers a more authentic CarPlay simulator, which requires a real iPhone connected to a Mac. It behaves just like a car’s CarPlay system and can be downloaded as part of “Additional Tools for Xcode“. After launching the simulator only the iPhone needs to be connected by cable and then CarPlay should start automatically after a moment. If not, just press the button to connect and disconnect again. Contrary to the other CarPlay simulator, this one also simulates car controls like the scroll wheel or steering wheel play/pause button and from my experience behaves just as a real car would.
iOS differences
If your app supports multiple iOS versions, be prepared for some discrepancies. We encountered the following differences:
iOS 15:
- The completion block of setRootTemplate of the interface controller is not called after a root template has been presented. For future iOS versions, this works as expected.
- To circumvent this, the delegate method templateDidAppear can be used which is called for every presented template.
iOS 17.4
- Starting with this iOS version, it is possible to add subtitles (apple documentation) to CPListImageRowItem.
Pagination
When displaying a section with a lot of elements and you don’t want to fetch all elements at once, the options to implement pagination in CarPlay are limited. Unfortunately, there is no delegate method that informs us whether a certain list element was seen by the user. One idea is to add a CPListItem that works as a load-more button for the user. For instance, if 20 items are already displayed and you want to add 20 more to the list, creating new CPListItems for all 40 items would cause the UI to flicker. To prevent this, the previously displayed CPListItem should be stored, and a new CPListItem should be created only for the 20 new items. By passing these 40 CPListItems (20 old and 20 new) to the section, you can avoid any UI flickering.
CarPlay limits
When developing an app in CarPlay one will notice pretty quickly that there is not much room for creativity and that the system is rather restrictive. However, you might not be aware of all restrictions immediately.
- In a CPTemplate, only 500 elements can be displayed and this includes sections and list items. Apple Music appears to not have this restriction, but the rest of us do.
- At maximum five templates can be in the view hierarchy simultaneously. A root template already counts as the first screen and this count is only reset when visiting another root template. Presenting the fullscreen player will not reset this count, but count as another screen. If this limit is exceeded, so if the sixth template is presented, the app will crash.
Weak references
During development, we observed that a strong reference needs to be kept for the templates that are currently part of the view hierarchy, otherwise they may be dismissed. Therefore, if you encounter issues with templates not being presented, retaining a reference to these templates could solve the problem.
CPNowPlayingTemplate
This is the component for the fullscreen player in CarPlay and only very little customization is possible here. Most of the UI like the play/pause, next, previous button, and so on are controlled by MPRemoteCommand. These commands are also used for controlling the iPhone lock screen player. So the decision whether a next and previous button or a skip a few seconds forward and backward button is displayed depends on which command is enabled. The commands also control the state of the corresponding buttons.
However, you can also add custom buttons in the bottom bar on the screen by creating CPNowPlayingButton and adding those buttons to the shared template with updateNowPlayingButtons().
CPTemplate
When deciding whether to use a CPAlertTemplate or just the emptyViewTitleVariants of a CPTemplate you have to be aware that action buttons can only be added to an alert template and that an empty view of a template can only display text and often might not serve as a good option for handling an error state.
If you are interested in developing an app for CarPlay or need any help along the way, feel free to reach out to us at inovex!
