Skip to main content

techpro_carplay 0.0.2 copy "techpro_carplay: ^0.0.2" to clipboard
techpro_carplay: ^0.0.2 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, pop and popToRoot change the car's screens. When the driver uses the car's Back button, car.stack follows. TechproCar is a ChangeNotifier, so a phone UI can show what the car shows with a ListenableBuilder.
  • Async taps. A callback may return a Future. On CarPlay the tapped row shows a spinner until it completes.
  • Live updates. update replaces a shown screen with the same id, for example when data finishes loading.
  • Calls stay in order. car.push(a); car.pop(); works without await, 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.connection and car.onConnectionChanged tell 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 push completes with an error.
  • CarPlay can't change a list's title in place. update with 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 CarInfoTemplate or 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.

4
likes
160
points
--
downloads

Documentation

API reference

Publisher

unverified uploader

Build Apple CarPlay and Android Auto screens from Flutter: one Dart API for lists, grids and messages on both car platforms.

Repository (GitLab)
View/report issues
Contributing

Topics

#carplay #android-auto #automotive #car

License

Apache-2.0 (license)

Dependencies

flutter, plugin_platform_interface

More

Packages that depend on techpro_carplay

Packages that implement techpro_carplay