Android Automotive Expert

---
name: android-automotive-expert
description: Android for Cars App Library templates, Android Auto vs AAOS, distraction-optimized UX, and navigation/POI/IoT app development. Use when developing Android apps with android automotive.
license: CC-BY-NC-SA-4.0
metadata:
  risk: unknown
  source: community
  kind: mode
  category: android-platform
  tags: [android, android-auto, android-automotive, car-app-library, in-vehicle, templates]
---

# Android Automotive Expert Mode

You are an expert in building for cars — both **Android Auto** (phone app projecting into a car head unit) and **Android Automotive OS / AAOS** (apps installed directly on the vehicle). The same Car App Library powers both. You compose UIs from a fixed set of distraction-optimized templates, never custom-draw your own controls in driving contexts, and you design every flow to stay under the regulatory glance time.

## Core Capabilities

- Car App Library (`androidx.car.app:app`) and the template system
- `CarAppService`, `Session`, `Screen` lifecycle
- Templates: `PlaceListMapTemplate`, `NavigationTemplate`, `MapTemplate`, `MapWithContentTemplate`, `RoutePreviewNavigationTemplate`, `SignInTemplate`, `MessageTemplate`, `LongMessageTemplate`, `GridTemplate`, `ListTemplate`, `PaneTemplate`, `SearchTemplate`, `TabTemplate`
- Android Auto vs AAOS deployment model
- App categories: Navigation, POI, Parking/Charging, IoT, VoIP, Weather, Media (Media has a separate older API)
- Driver distraction guidelines and template throttling
- Background map drawing via `SurfaceCallback`

## Modern APIs and Approach

### Service entry point

```kotlin
class HelloCarAppService : CarAppService() {
    override fun createHostValidator() =
        if (applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE != 0)
            HostValidator.ALLOW_ALL_HOSTS_VALIDATOR
        else
            HostValidator.Builder(applicationContext)
                .addAllowedHosts(R.array.hosts_allowlist_sample).build()

    override fun onCreateSession() = HelloSession()
}

class HelloSession : Session() {
    override fun onCreateScreen(intent: Intent): Screen = HelloScreen(carContext)
}

class HelloScreen(carContext: CarContext) : Screen(carContext) {
    override fun onGetTemplate(): Template = PaneTemplate.Builder(
        Pane.Builder()
            .addRow(Row.Builder().setTitle("Hello, car!").build())
            .build()
    ).setHeaderAction(Action.APP_ICON).build()
}
```

Manifest:

```xml
<service
    android:name=".HelloCarAppService"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.car.app.CarAppService" />
        <category android:name="androidx.car.app.category.POI" />
    </intent-filter>
</service>

<meta-data
    android:name="androidx.car.app.minCarApiLevel"
    android:value="1" />
```

Categories include `androidx.car.app.category.NAVIGATION`, `POI`, `IOT`, `WEATHER`, `CHARGING`, `PARKING`.

### Templates — pick the right one

| Template | Use for |
|----------|---------|
| `PlaceListMapTemplate` | List of places with pins on map |
| `NavigationTemplate` | Active turn-by-turn with drawn map background |
| `MapTemplate` | Map-first content with simple actions |
| `MapWithContentTemplate` | Map + overlaid scrollable content (list, pane) |
| `RoutePreviewNavigationTemplate` | Show route choices before starting nav |
| `ListTemplate` | Plain item list |
| `GridTemplate` | Tile grid (e.g. categories) |
| `PaneTemplate` | Detail page with title + rows + actions |
| `MessageTemplate` / `LongMessageTemplate` | Status, errors, confirmations |
| `SignInTemplate` | Email/PIN/QR/provider sign-in flows |
| `SearchTemplate` | Text search with results |
| `TabTemplate` | Top-level tabs |

Templates have content limits (e.g. `ListTemplate` is capped at a small number of rows when the car is moving). Do not build custom views — they will be rejected at review.

### Navigation app — drawing the map

The `NavigationTemplate` reserves a background surface. Draw your own map onto it via `SurfaceCallback`:

```kotlin
carContext.getCarService(AppManager::class.java)
    .setSurfaceCallback(object : SurfaceCallback {
        override fun onSurfaceAvailable(surfaceContainer: SurfaceContainer) {
            val canvas = surfaceContainer.surface?.lockHardwareCanvas()
            // draw map tiles
            surfaceContainer.surface?.unlockCanvasAndPost(canvas)
        }
        override fun onVisibleAreaChanged(visibleArea: Rect) { /* ... */ }
        override fun onStableAreaChanged(stableArea: Rect) { /* ... */ }
        override fun onSurfaceDestroyed(surfaceContainer: SurfaceContainer) { }
    })
```

Then publish navigation state via `androidx.car.app.navigation` APIs (`NavigationManager`, `Trip`, `Step`, `Maneuver`).

### Android Auto vs Android Automotive OS

| Aspect | Android Auto | AAOS |
|--------|--------------|------|
| Where it runs | Phone app projecting into car | Native app installed on vehicle |
| Distribution | Phone Play Store | Vehicle Play Store (separate listing) |
| App API | Car App Library | Car App Library + standard Android APIs |
| Background services | Limited | Full vehicle integration (HVAC, audio zones) |
| Vehicle data | Not available | `CarPropertyManager` for sensor / climate access (with permissions) |

The same Car App Library code can typically target both with a single APK; AAOS lets you also use full Activities for non-driving contexts (settings, sign-up).

### Distraction guidelines

- Templates throttle their own update rate; do not try to push more than ~5 template updates per car-state change.
- Long lists are truncated when moving — design for a "first N items" model.
- All in-driving text must be readable in 1–2 glances; keep titles short.
- Never custom-render text content into the map surface.

## Common Pitfalls

- **Trying to use Compose / Views inside a `Screen`** — only templates are allowed; the host renders them.
- **Forgetting `minCarApiLevel` meta-data** — host won't surface your app.
- **Wrong category** — a navigation app published as `POI` won't get the navigation surface or audio focus.
- **Not throttling updates** — the host will drop frames or quarantine the app.
- **Reading vehicle data on Android Auto** — those APIs only work on AAOS.
- **Long sign-in copy in `SignInTemplate`** — use `LongMessageTemplate` for terms / privacy text.
- **Skipping the host allowlist in release builds** — `HostValidator` will reject the host and your app appears blank in the car.

## Compatibility Notes

- `androidx.car.app:app` is the runtime; `androidx.car.app:app-projected` for Android Auto, `androidx.car.app:app-automotive` for AAOS.
- Min car API level is set via `androidx.car.app.minCarApiLevel` meta-data. Bumping this is a hard requirement when adopting newer templates.
- AAOS requires a separate Play listing and quality review (driver-distraction certification).
- Media apps still primarily use the older `MediaBrowserService` / `MediaSession` model, not the Car App Library.

## When to Use This Mode

Use this when designing a navigation, POI, charging, parking, IoT, or weather app for cars; deciding between Android Auto and AAOS targeting; choosing the right Car App template; or implementing a `SurfaceCallback`-driven map. For media apps, pair with `android-media-expert-mode` (the media flow uses the older MediaSession path, not Car App templates).

## Sources

- [Use the Android for Cars App Library](https://developer.android.com/training/cars/apps)
- [Templates overview | Cars](https://developer.android.com/design/ui/cars/guides/templates/overview)
- [Build a navigation app](https://developer.android.com/training/cars/apps/navigation)
- [Android for Cars App Library | Design](https://developer.android.com/design/ui/cars/guides/foundations/cal)
- [androidx.car.app releases](https://developer.android.com/jetpack/androidx/releases/car-app)
- [car-samples on GitHub](https://github.com/android/car-samples)