Carplay Audio App Programming Guide March 2017 Contents
Total Page:16
File Type:pdf, Size:1020Kb
CarPlay Audio App Programming Guide March 2017 Contents Introduction 3 CarPlay Audio Apps 4 Development Environment CarPlay audio app entitlement 5 Simulator 7 CarPlay Audio App Design 8 Show an app icon on the CarPlay home screen 9 Present a hierarchical list to navigate and select audio content 10 Show media information in the Now Playing screen 14 Handle remote control events 15 Best Practices 16 Publishing Your CarPlay Audio App 20 Revision History 21 Copyright © 2019 Apple Inc. All Rights Reserved. 2 Introduction CarPlay is a smarter, safer way to use your iPhone in the car. CarPlay takes the things you want to do with your iPhone while driving and puts them right on your car's built-in display. In addition to getting directions, making calls, and sending and receiving messages, CarPlay supports audio apps, messaging apps and automaker apps that you’ve downloaded to your iPhone. This guide describes how to create a CarPlay audio app. CarPlay audio app development requires iOS 7.1 or later and Xcode 5.1 or later. Copyright © 2019 Apple Inc. All Rights Reserved. 3 CarPlay Audio Apps Users download CarPlay audio apps from the App Store and use them on iPhone like any other app. When an iPhone with your audio app is connected to a CarPlay vehicle compatible with your app, your app’s icon appears on the CarPlay home screen. CarPlay audio apps are designed to look and feel like the built-in Music app. CarPlay audio apps work by providing metadata to populate the provided user interface, and by responding to user actions such as track selection or media control. iOS manages the display of your app on the CarPlay screen and handles the interface with the car. Your app does not have to worry about screen resolutions, or input hardware such as touchscreens, knobs, or steering wheel controls. Audio apps must meet the basic requirements defined in CarPlay APIs Addendum to the iOS Developer Program License Agreement. Also see Human Interface Guidelines for CarPlay Apps. Copyright © 2019 Apple Inc. All Rights Reserved. 4 Development Environment CarPlay audio app entitlement Audio apps require a CarPlay audio app entitlement. To obtain the entitlement, sign and return the CarPlay APIs Addendum to the iOS Developer Program License Agreement and let Apple know the Apple Developer Program Team ID that you intend to use when publishing your app on the App Store. Apple will create a CarPlay entitlement and contact you. Once the entitlement is created, log in to your account on the Apple Developer website and create a new Provisioning Profile that includes the CarPlay audio app entitlement. Copyright © 2019 Apple Inc. All Rights Reserved. 5 After you have created a new Provisioning Profile that supports CarPlay, be sure to import it into Xcode. The Simulator will not recognize your CarPlay audio app without the presence of a Provisioning Profile that supports CarPlay. In your Xcode project, you will also need to create an Entitlements.plist file in your project, if you don't have one already, and include a key for the CarPlay audio app entitlement as a Boolean: <key>com.apple.developer.playable-content</key> <true/> In Xcode, make sure that your target project setting CODE_SIGN_ENTITLEMENTS is set to the path of your Entitlements.plist file. Copyright © 2019 Apple Inc. All Rights Reserved. 6 Simulator To activate CarPlay support in the Simulator, type: defaults write com.apple.iphonesimulator CarPlay -bool YES from the Terminal, then quit and launch the Simulator. From the Simulator menu, select Hardware, External Displays and CarPlay to show the CarPlay screen. The CarPlay screen will be blank until your app is run. While the Simulator is useful during development, certain CarPlay features are not available in the Simulator and you should not rely on it as the sole method to develop your app. Test your app on real hardware to observe interaction with other CarPlay features such as the built-in Music app, interruptions from phone calls, and audio mixing with turn-by-turn spoken directions. It is highly recommended to develop audio apps using a car or aftermarket head unit that supports wireless CarPlay. This will allow you to run CarPlay wirelessly while iPhone is simultaneously connected to Xcode on your Mac using a Lightning to USB cable. Copyright © 2019 Apple Inc. All Rights Reserved. 7 CarPlay Audio App Design Complete the following tasks to add CarPlay support to your audio app: Task Include the CarPlay audio app • Add com.apple.developer.playable-content to entitlement Entitlements.plist. Show an app icon on the CarPlay • Add a CarPlay-specific app icon asset. home screen Present a hierarchical list to navigate • Implement MPPlayableContentDataSource and assign the and select audio content MPPlayableContentManager dataSource property. • Implement MPPlayableContentDelegate and assign the MPPlayableContentManager delegate property. Show media information in the Now • Update MPNowPlayingInfoCenter with information about the Playing screen currently playing audio. Handle remote control events • Support MPRemoteCommandCenter events. Copyright © 2019 Apple Inc. All Rights Reserved. 8 Show an app icon on the CarPlay home screen Provide app icon assets for rendering in CarPlay. Your CarPlay icon should look similar to your app icon displayed on iPhone. Your app icon will not appear on the CarPlay home screen if the app is missing the CarPlay audio app entitlement. To specify app icon assets, turn on the CarPlay app icon asset in Xcode and drag your icon into the image well for CarPlay. Copyright © 2019 Apple Inc. All Rights Reserved. 9 Present a hierarchical list to navigate and select audio content CarPlay audio apps provide a list that allows the user to navigate and select audio content. The list may be as simple as a short, static list of audio content, or a dynamic list with content arranged in a navigable hierarchy. Starting with iOS 10, audio apps can also implement tabs that appear across the top of the screen. Audio playback starts when the user explicitly selects an item to play. To provide a list of audio content, support the MPPlayableContentManager data source protocol (MPPlayableContentDataSource) and delegate (MPPlayableContentDelegate). When your app is launched, set the data source protocol and delegate using sharedContentManager. For details, see MPPlayableContentDataSource and MPPlayableContentDelegate below. If you provide a list, the root level list must not be empty. If your root level list is dynamically generated, maintain a cache or present default content so that some information is shown even when the network is unavailable. Remember that users are more likely to encounter poor network reception while driving, and if they encounter an empty list when your app is launched, it will look like your app is not working. Starting with iOS 10, a loading screen will be shown while your app is generating content, and will show an error screen after a period of time if your app does not load content. The user will have the ability to retry fetching content when they are presented with this error screen. If you provide a list, never start audio playback until the user explicitly selects a playable item. Users expect to be able to browse your list of audio content while the previous audio source, such as the car’s FM radio or another audio app is still playing. Copyright © 2019 Apple Inc. All Rights Reserved. 10 MPPlayableContentDataSource The data source protocol is invoked when CarPlay needs to present a list of audio content. You receive an NSIndexPath which indicates which list in the hierarchy is being requested. Your app responds with the number of items in the requested list and an MPContentItem for each item in the list. MPContentItem contains metadata for an item in the list. You should always include an identifier and a title. You must also specify whether the item is a container or a playable item. Starting with iOS 8.3, every MPContentItem must have either the container or playable property set to YES. If they are both set to NO then the item will not be functional. Container items are drawn with a chevron icon on the edge indicating that they lead to the next level in the hierarchy, and the view will be animated appropriately when the item is selected. If the item is playable, you are expected to play audio when the item is selected. The following is a list of properties you can set with each MPContentItem. Property Description identifier A unique identifier for the item. This is required for the MPPlayableContent APIs to reference and update content accordingly. title The title of the item. Usually this is a track name if representing playable content, or a container’s name such as a playlist or album. subtitle The subtitle of the item. If the subtitle were representing a song, it would represent the artist or composer. artwork The artwork for the item. playbackProgress Represents the playback progress of the item. You must implement childItemsDisplayPlaybackProgressAtIndexPath in MPPlayableContentDataSource in order to display playback progress. Otherwise, the framework will assume playback progress is not supported for any content items. explicitContent The item contains explicit content which may not be suitable for some audiences. Available in iOS 10 and later. streamingContent The item is not local to the device and initiating playback for this item will incur data usage. Available in iOS 10 and later. container The item is a container of other items, such as media content or other containers. Examples of containers include playlists, albums, and radio stations. playable The item is a playable content, and will load the Now Playing screen and initiate playback when tapped. Copyright © 2019 Apple Inc. All Rights Reserved. 11 MPPlayableContentDelegate The delegate is called when the user selects a playable item.