techpro_carplay 0.0.1
techpro_carplay: ^0.0.1 copied to clipboard
Build Apple CarPlay and Android Auto screens from Flutter: one Dart API for lists, grids and messages on both car platforms.
techpro_carplay #
Build Apple CarPlay and Android Auto screens from Flutter with one Dart API.
Status: early development (0.0.x). CarPlay and Android Auto both work. The API may still change before 0.1.0.
Neither CarPlay nor Android Auto lets an app draw its own UI on the car display. Both offer a few fixed screen types, called templates, that the car draws itself so they are safe to use while driving. techpro_carplay lets you describe those templates once in Dart and shows them natively on both systems.
| Dart | CarPlay | Android Auto |
|---|---|---|
CarListTemplate: rows in sections, loading and empty states |
CPListTemplate |
ListTemplate |
CarGridTemplate: up to 8 buttons with images |
CPGridTemplate |
GridTemplate |
CarInfoTemplate: up to 4 label/value rows and 2 buttons |
CPInformationTemplate |
PaneTemplate |
CarAlert: a title, a message and up to 2 buttons |
CPAlertTemplate |
MessageTemplate |
Usage #
import 'package:techpro_carplay/techpro_carplay.dart';
final car = TechproCar.instance;
await car.setRoot(CarListTemplate(
id: 'stores',
title: 'Stores',
loading: true,
));
final stores = await api.nearbyStores();
await car.update(CarListTemplate(
id: 'stores',
title: 'Stores',
items: [
for (final store in stores)
CarListItem(
title: store.name,
subtitle: store.distance,
image: const CarImage.asset('assets/store.png'),
showsChevron: true,
onSelect: () => car.push(CarInfoTemplate(
title: store.name,
rows: [CarInfoRow(label: 'Open', value: store.hours)],
actions: [CarAction(title: 'Back', onPressed: car.pop)],
)),
),
],
));
What you get:
- One stack, kept in sync.
setRoot,push,popandpopToRootchange the car's screens. When the driver uses the car's Back button,car.stackfollows.TechproCaris aChangeNotifier, so a phone UI can show what the car shows with aListenableBuilder. - Async taps. A callback may return a
Future. On CarPlay the tapped row shows a spinner until it completes. - Live updates.
updatereplaces a shown screen with the sameid, for example when data finishes loading. - Calls stay in order.
car.push(a); car.pop();works withoutawait, and an event from the car in between is never applied twice. - Limits are checked in Dart. A 9th grid item or a 6th screen throws a clear error right away instead of failing inside the car.
- Works before a car connects. Screens set earlier appear as soon as
CarPlay or Android Auto connects.
car.connectionandcar.onConnectionChangedtell you when that happens.
Every alert button closes the alert, and pushing a new screen closes an open alert too. On Android Auto, which has no pop-ups, an alert is shown as a full screen that Back also closes.
Limits of the car systems #
Both systems limit what an app may show, depending on its category. Pick the category that really matches your app; Apple and Google check it before the app can be released.
CarPlay
- Each category has its own set of allowed templates and a maximum number of screens. Some categories allow only 2 or 3 screens, the root included, so keep flows short. The rules are in Apple's CarPlay Developer Guide.
- Pushing a screen the category doesn't allow, or one too deep, fails:
the future returned by
pushcompletes with an error. - CarPlay can't change a list's title in place.
updatewith a new title works on the top screen (it replaces it) and fails on screens below it. - Lists longer than CarPlay's limit are cut. On iOS 18.4 and later a loading list shows a spinner; before that it shows "Loading…".
Android Auto
- A task can show at most 5 templates, and the 5th must be a
CarInfoTemplateor an alert. techpro_carplay checks this when you push. - Changing what a screen shows counts as one more template, unless only details change: the same title and the same number of rows. Going from loading to loaded is always free. Going back to a screen gives the steps back.
- There is no general category. Allowed categories include points of interest (parking, charging), Internet of Things and weather; see Android for Cars.
- Lists and grids longer than the host's limit are cut, and sections of a grouped list without a header get an empty one.
iOS setup (CarPlay) #
CarPlay runs in its own scene and can open your app while the phone screen stays off. Your Dart code has to run in that case too, so the app starts one shared Flutter engine at launch.
1. ios/Runner/AppDelegate.swift
import Flutter
import UIKit
@main
@objc class AppDelegate: FlutterAppDelegate {
let engine = FlutterEngine(name: "main")
override func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
engine.run()
GeneratedPluginRegistrant.register(with: engine)
return super.application(application, didFinishLaunchingWithOptions: launchOptions)
}
}
class SceneDelegate: FlutterSceneDelegate {
override func scene(
_ scene: UIScene,
willConnectTo session: UISceneSession,
options connectionOptions: UIScene.ConnectionOptions
) {
if let windowScene = scene as? UIWindowScene,
let app = UIApplication.shared.delegate as? AppDelegate {
let window = UIWindow(windowScene: windowScene)
window.rootViewController = FlutterViewController(engine: app.engine, nibName: nil, bundle: nil)
window.makeKeyAndVisible()
self.window = window
}
super.scene(scene, willConnectTo: session, options: connectionOptions)
}
override func sceneDidDisconnect(_ scene: UIScene) {
window = nil
super.sceneDidDisconnect(scene)
}
}
2. ios/Runner/Info.plist: remove UIMainStoryboardFile and add:
<key>UIApplicationSceneManifest</key>
<dict>
<key>UIApplicationSupportsMultipleScenes</key>
<false/>
<key>UISceneConfigurations</key>
<dict>
<key>UIWindowSceneSessionRoleApplication</key>
<array>
<dict>
<key>UISceneConfigurationName</key>
<string>Phone</string>
<key>UISceneDelegateClassName</key>
<string>$(PRODUCT_MODULE_NAME).SceneDelegate</string>
</dict>
</array>
<key>CPTemplateApplicationSceneSessionRoleApplication</key>
<array>
<dict>
<key>UISceneConfigurationName</key>
<string>CarPlay</string>
<key>UISceneClassName</key>
<string>CPTemplateApplicationScene</string>
<key>UISceneDelegateClassName</key>
<string>TechproCarSceneDelegate</string>
</dict>
</array>
</dict>
</dict>
3. Entitlement. Add a Runner.entitlements file with your CarPlay
category, for example com.apple.developer.carplay-driving-task set to
true, and set it as Code Signing Entitlements of the Runner target. The
Simulator accepts it right away; for devices and the App Store, Apple has to
approve the category for your app. Some categories need a newer iOS than
techpro_carplay's minimum of 15; driving task, for one, needs iOS 16.
To try it, run the app on an iOS Simulator and choose I/O → External Displays → CarPlay. The example app has all three steps.
Android setup (Android Auto) #
Android Auto starts your app through a service, possibly without opening the phone screen. As on iOS, the phone and the car share one Flutter engine, which techpro_carplay starts when needed.
1. MainActivity.kt
import android.content.Context
import com.techprosubh.techpro_carplay.TechproCarEngine
import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.engine.FlutterEngine
class MainActivity : FlutterActivity() {
override fun provideFlutterEngine(context: Context): FlutterEngine = TechproCarEngine.get(context)
override fun shouldDestroyEngineWithHost(): Boolean = false
}
Without this step the phone and the car would each run their own copy of your app. techpro_carplay lets only the shared engine drive the car and logs a warning pointing here.
2. android/app/src/main/AndroidManifest.xml, inside <application>:
<service
android:name="com.techprosubh.techpro_carplay.TechproCarAppService"
android:exported="true">
<intent-filter>
<action android:name="androidx.car.app.CarAppService" />
<!-- Your app's category, e.g. POI, IOT or WEATHER -->
<category android:name="androidx.car.app.category.POI" />
</intent-filter>
</service>
<meta-data
android:name="com.google.android.gms.car.application"
android:resource="@xml/automotive_app_desc" />
<meta-data
android:name="androidx.car.app.minCarApiLevel"
android:value="1" />
3. android/app/src/main/res/xml/automotive_app_desc.xml
<automotiveApp>
<uses name="template" />
</automotiveApp>
Debug builds accept any Android Auto host, so you can test with the
Desktop Head Unit.
Release builds only accept Google's hosts; subclass TechproCarAppService
and override createHostValidator to change that.
Testing #
package:techpro_carplay/testing.dart has a fake car that runs in ordinary
Flutter tests. It keeps its own screen stack, and you can tap, press Back
and connect:
import 'package:techpro_carplay/techpro_carplay.dart';
import 'package:techpro_carplay/testing.dart';
void main() {
late FakeCarPlatform car;
setUp(() => car = FakeCarPlatform.install());
tearDown(TechproCar.resetForTesting);
test('tapping a store opens its details', () async {
await showStores();
await car.tap('store-1');
expect(car.screens.last['title'], 'Main Street');
await car.pressBack();
expect(car.screens, hasLength(1));
});
}
Platform requirements #
| CarPlay | Android Auto | |
|---|---|---|
| Minimum OS | iOS 15 (some categories need more) | Android 7.0 (API 24) |
| Before release | Apple approves your CarPlay category | Google Play reviews the app for Android Auto |
| To test | iOS Simulator → I/O → External Displays → CarPlay | Desktop Head Unit (DHU) |
License #
Apache 2.0. See LICENSE.