@iternio/react-native-auto-play 0.1.18 → 0.2.0-alpha.2

package/README.md

@@ -220,6 +220,84 @@ You can customize certain behaviors of the library on Android Auto by setting pr
     ```
     The default values are `1000` for the delay and `500` for the duration.
 
+### Android Automotive
+
+This library also supports Android Automotive. To enable Android Automotive support, you need to configure a few properties in your Android project.
+
+-   **`minSdkVersion`**: The minimum API level for Android Automotive is 29. You must set `minSdkVersion` to at least `29`. For Android Auto, the minimum is `24`.
+
+-   **`isAutomotiveApp` flag**: You need to inform the library if this is an Automotive app by setting the `isAutomotiveApp` property to `true`. For Android Auto, it should be `false`.
+
+You can set these properties directly in your `android/gradle.properties` file:
+```properties
+# For Android Automotive
+minSdkVersion=29
+isAutomotiveApp=true
+```
+
+Alternatively, if you need to support different build variants (e.g., for both Android Auto and Android Automotive from the same codebase), using `react-native-config` is the recommended approach.
+
+1.  Install `react-native-config`:
+    ```bash
+    yarn add react-native-config
+    ```
+
+2.  Create different `.env` files for your variants. Create a default `.env` for Android Auto:
+    ```
+    # .env (for Android Auto)
+    isAutomotiveApp=false
+    minSdkVersion=24
+    ```
+    And an `.env.automotive` for Android Automotive:
+    ```
+    # .env.automotive
+    minSdkVersion=29
+    isAutomotiveApp=true
+    ```
+
+3.  In your `android/app/build.gradle`, apply the configuration from `react-native-config` based on your build flavors.
+    ```groovy
+    // android/app/build.gradle
+
+    project.ext.envConfigFiles = [
+        automotive: ".env.automotive",
+        // other flavors...
+    ]
+    apply from: project(':react-native-config').projectDir.getPath() + "/dotenv.gradle"
+
+    if (project.ext.has("env")) {
+        rootProject.ext.minSdkVersion = project.ext.env.minSdkVersion
+        rootProject.ext.isAutomotiveApp = project.ext.env.isAutomotiveApp
+    }
+    ```
+Adjust to the build variants your app provides. Check the example app for details.
+
+This approach allows you to dynamically set the required flags based on your build variant, which is demonstrated in the example app.
+
+#### App launch on Android Automotive
+
+Android Automotive requires you to remove your app activity since it invokes the libraries Android Auto service in a different way. Not doing so will bring up 2 app icons on the Android Automotive launcher.
+To get rid of your default activity, do an automotive specific build variant and add this AndroidManifest.xml for that variant.
+```xml
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+
+    <application>
+        <activity
+            android:name=".MainActivity"
+            tools:node="remove" /> <!-- remove main activity -->
+    </application>
+
+</manifest>
+```
+For details check the example app and its build variants.
+
+#### A Note on Android Studio
+
+When using build variants, Android Studio may not be aware of the selected variant during a Gradle sync. This can cause the IDE to show the incorrect implementation of native classes like `AndroidTelemetryObserver` (e.g., it might show the Android Auto version instead of the Automotive version).
+
+To work around this and allow for debugging or enhancing the Android Automotive-specific implementation, you can temporarily set the automotive flags in your `gradle.properties` file or your default `.env` file before running a Gradle sync.
+
 ## Icons
 The library is using [Material Symbols](https://fonts.google.com/icons) for iconography. The font is bundled with the library, so no extra setup is required. You can use these icons on both Android Auto and CarPlay.
 
@@ -431,13 +509,39 @@ Below is a concise overview of the most important props per template. Optional p
 | `headerActions` | `HeaderActionsAndroid<MessageTemplate>` | ❌ | Android-only header actions. |
 | `mapConfig` | `BaseMapTemplateConfig<MessageTemplate>` | ❌ | Android map-with-content layout. |
 
+#### SignInTemplateConfig (Android-only)
+
+| Prop | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `signInMethod` | `SignInMethod` | ✅ | The sign-in method configuration. Can be QRSignIn, PinSignIn, InputSignIn. |
+| `title` | `string` | ❌ | Header title. |
+| `additionalText` | `string` | ❌ | Additional descriptive text. |
+| `instructions` | `string` | ❌ | Sign-in Instructions text. |
+| `actions` | `ActionButton<SignInTemplate>[]` | ❌ | Up to 2 buttons. |
+| `headerActions` | `SignInHeaderActions<SignInTemplate>` | ❌ | Header actions. See **Header Actions** below. |
+
+**SignInMethod**
+
+| Method | Type | Notes |
+| --- | --- | --- |
+| QR | `QrSignIn` | QR Code sign in |
+| PIN | `PinSignIn` | PIN Code sign in (1–12 characters) |
+| Input | `InputSignIn` | Text sign in, for example mail/username and password |
+
+For InputSignIn the keyboard and input fields can be configured with following properties:
+
+**KeyboardType enum:** `DEFAULT`, `EMAIL`, `PHONE`, `NUMBER`
+
+**TextInputType enum:** `PASSWORD`, `DEFAULT`
+
+
 ### Header Actions (Important)
 
 On Android, header actions may be omitted, although this is not recommended. If `headerActions` is `undefined`, the system automatically renders the app icon in the header. Because Android Auto enforces monochrome icons, this can result in a poor-looking button.
 
 **Use these rules to avoid crashes:**
 
-1. **For List/Grid/Information/Search/Message templates on Android**, always pass the structured object format (alignment is implicit via `startHeaderAction`/`endHeaderActions`):
+1. **For List/Grid/Information/Search/Message/SignIn templates on Android**, always pass the structured object format (alignment is implicit via `startHeaderAction`/`endHeaderActions`):
 
 ```ts
 const headerActions: HeaderActions<MyTemplate> = {
@@ -657,20 +761,39 @@ new ListTemplate({
 -   `useVoiceInput()`: Access voice input functionality - Android Auto only.
 -   `useSafeAreaInsets()`: Get safe area insets for any root component.
 -   `useFocusedEffect()`: A useEffect alternative that executes when the specified component is visible to the user - use any of the `AutoPlayModules` enum or a cluster uuid to sepcify the component the effect should listen for.
--   `useAndroidAutoTelemetry()`: Access to car telemetry data on Android Auto.
+-   `useAndroidAutoTelemetry()`: Access to car telemetry data on Android Auto and Android Automotive.
     ```tsx
     import {
       useAndroidAutoTelemetry,
       AndroidAutoTelemetryPermissions,
+      AndroidAutomotiveTelemetryPermissions,
     } from '@iternio/react-native-auto-play';
+    import Config from 'react-native-config';
 
     const MyComponent = () => {
       const { telemetry, permissionsGranted, error } = useAndroidAutoTelemetry({
-        requiredPermissions: [
-          AndroidAutoTelemetryPermissions.Speed,
-          AndroidAutoTelemetryPermissions.Energy,
-          AndroidAutoTelemetryPermissions.Odometer,
-        ],
+        requiredPermissions:
+          Config.isAutomotiveApp === 'true'
+            ? [
+                AndroidAutomotiveTelemetryPermissions.Info,
+                AndroidAutomotiveTelemetryPermissions.Speed,
+                AndroidAutomotiveTelemetryPermissions.Energy,
+                AndroidAutomotiveTelemetryPermissions.ExteriorEnvironment,
+                AndroidAutomotiveTelemetryPermissions.EnergyPorts,
+              ]
+            : [
+                AndroidAutoTelemetryPermissions.Speed,
+                AndroidAutoTelemetryPermissions.Energy,
+                AndroidAutoTelemetryPermissions.Odometer,
+              ],
+        automotivePermissionRequest:
+          Config.isAutomotiveApp === 'true'
+            ? {
+                cancelButtonText: 'Cancel',
+                grantButtonText: 'Grant',
+                message: 'Grant permission for vehicle telemetry access.',
+              }
+            : undefined,
       });
 
       if (!permissionsGranted) {
@@ -688,6 +811,14 @@ new ListTemplate({
           <Text>Battery Level: {telemetry?.batteryLevel?.value}%</Text>
           <Text>Range: {telemetry?.range?.value} km</Text>
           <Text>Odometer: {telemetry?.odometer?.value} km</Text>
+          <Text>Selected Gear: {telemetry?.selectedGear?.value}</Text>
+          <Text>Outside Temperature: {telemetry?.envOutsideTemperature?.value}°C</Text>
+          <Text>EV Charge Port Connected: {String(telemetry?.evChargePortConnected?.value)}</Text>
+          <Text>EV Battery Charge Rate: {telemetry?.evBatteryInstantaneousChargeRate?.value} kW</Text>
+          <Text>Parking Brake On: {String(telemetry?.parkingBrakeOn?.value)}</Text>
+          <Text>Vehicle Name: {telemetry?.vehicle?.name?.value}</Text>
+          <Text>Vehicle Manufacturer: {telemetry?.vehicle?.manufacturer?.value}</Text>
+          <Text>Vehicle Year: {telemetry?.vehicle?.year?.value}</Text>
         </View>
       );
     }
@@ -699,6 +830,15 @@ new ListTemplate({
     - `range`: Range in km.
     - `odometer`: Odometer in km.
     - `vehicle`: Vehicle information (model name, model year, manufacturer).
+    - `selectedGear`: The currently selected gear, one of the `VehicleGear` enum:
+       - Neutral = 1
+       - Reverse = 2
+       - Park = 4
+       - Drive = 8
+    - `envOutsideTemperature`: The outside temperature in °C.
+    - `evChargePortConnected`: Whether the EV charge port is connected.
+    - `evBatteryInstantaneousChargeRate`: The instantaneous charge rate of the EV battery in kW.
+    - `parkingBrakeOn`: Whether the parking brake is on.
 
 
 ### Scenes
@@ -735,7 +875,7 @@ CarPlayDashboard.setButtons([
 
 ### iOS
 
--   **Broken exceptions with `react-native-skia`**: When using `react-native-skia` up to version `2.4.7`, exceptions on iOS are not reported correctly. This is fixed in newer versions of `react-native-skia`. For more details, see this [pull request](https://github.com/Shopify/react-native-skia/pull/3595).
+-   **Broken exceptions with `react-native-skia`**: When using `react-native-skia` up to version `2.4.14`, exceptions on iOS are not reported correctly. This is fixed in newer versions of `react-native-skia`. For more details, see this [pull request](https://github.com/Shopify/react-native-skia/pull/3595) and [issue](https://github.com/Shopify/react-native-skia/issues/3635).
 -   **AppState on iOS**: The `AppState` module from React Native does not work correctly on iOS because this library uses scenes, which are not supported by the stock `AppState` module. This library provides a custom state listener that works for both Android and iOS. Use `HybridAutoPlay.addListenerRenderState` instead of `AppState`.
 -   **Timers stop on screen lock**: iOS stops all timers when the device's main screen is turned off. To ensure timers continue to run (which is often necessary for background tasks related to autoplay), a patch for `react-native` is required. A patch is included in the root `patches/` directory and can be applied using `patch-package`.
 -   **expo-splash-screen stuck on iOS**: The `expo-splash-screen` module is broken on iOS because it does not support scenes, which are used by this library. This can cause the splash screen to be stuck on either the mobile device or on CarPlay. To fix this, a patch for `expo-splash-screen` is included in the root `patches/` directory and can be applied using `patch-package`. After applying the patch, you can hide the splash screen for a specific scene by passing the module name to the `hide` or `hideAsync` function. The module name can be one of the values from the `AutoPlayModules` enum or the UUID of a cluster screen.
@@ -749,6 +889,10 @@ CarPlayDashboard.setButtons([
     // Hide the splash screen for the CarPlay screen
     hideAsync(AutoPlayModules.AutoPlayRoot);
     ```
+### Android
+-   **Broken exceptions with `react-native`** up to version 0.79
+When using react-native before 0.80.0 exceptions are broken and are reported as `Unknown runtime_error` or similar.
+See [this issue](https://github.com/mrousavy/nitro/issues/382) for details.
 
 ## Contributing
 

package/android/build.gradle

@@ -124,8 +124,20 @@ android {
           "${project.buildDir}/generated/source/codegen/java"
         ]
       }
+
+      if (getExtOrDefault("isAutomotiveApp") == "true") {
+        java.srcDirs += 'src/automotive/java'
+        manifest.srcFile 'src/automotive/AndroidManifest.xml'
+      } else {
+        java.srcDirs += 'src/auto/java'
+        manifest.srcFile 'src/main/AndroidManifest.xml'
+      }
     }
   }
+
+  if (getExtOrDefault("isAutomotiveApp") == "true") {
+    useLibrary 'android.car'
+  }
 }
 
 repositories {
@@ -133,7 +145,6 @@ repositories {
   google()
 }
 
-
 dependencies {
   // For < 0.71, this will be from the local maven repo
   // For > 0.71, this will be replaced by `com.facebook.react:react-android:$version` by react gradle plugin
@@ -151,5 +162,8 @@ dependencies {
     println("☎️ Enjoy your nitro powered Android Auto app!")
     implementation "androidx.car.app:app-projected:1.7.0"
   }
+
+  implementation 'com.google.android.gms:play-services-base:18.3.0'
+  implementation 'com.google.android.gms:play-services-auth:21.0.0'
 }
 

package/android/gradle.properties

@@ -1,5 +1,5 @@
 ReactNativeAutoPlay_kotlinVersion=2.1.20
-ReactNativeAutoPlay_minSdkVersion=23
+ReactNativeAutoPlay_minSdkVersion=24
 ReactNativeAutoPlay_targetSdkVersion=36
 ReactNativeAutoPlay_compileSdkVersion=36
 ReactNativeAutoPlay_ndkVersion=27.1.12297006

package/android/src/{main/java/com/margelo/nitro/swe/iternio/reactnativeautoplay/AndroidAutoTelemetryObserver.kt → auto/java/com/margelo/nitro/swe/iternio/reactnativeautoplay/AndroidTelemetryObserver.kt}

@@ -1,9 +1,5 @@
 package com.margelo.nitro.swe.iternio.reactnativeautoplay
 
-
-import android.os.Handler
-import android.os.Looper
-import android.util.Log
 import androidx.car.app.CarContext
 import androidx.car.app.hardware.CarHardwareManager
 import androidx.car.app.hardware.common.CarValue
@@ -15,23 +11,27 @@ import androidx.car.app.hardware.info.Speed
 import androidx.car.app.versioning.CarAppApiLevels
 import androidx.core.content.ContextCompat
 
-object AndroidAutoTelemetryObserver {
-    private var telemetryCallbacks: MutableList<(telemetry: Telemetry?, error: String?) -> Unit> =
-        ArrayList();
-
-    private var isRunning = false
+object AndroidTelemetryObserver : TelemetryObserver() {
     private var carContext: CarContext? = null
 
-    private val telemetryHolder = AndroidAutoTelemetryHolder()
-    private val handler = Handler(Looper.getMainLooper())
+    private val mModelListener = OnCarDataAvailableListener<Model> { model ->
+        val name = if (model.name.status == CarValue.STATUS_SUCCESS) {
+            model.name.value
+        } else null
+
+        val manufacturer = if (model.manufacturer.status == CarValue.STATUS_SUCCESS) {
+            model.manufacturer.value
+        } else null
+
+        val year = if (model.year.status == CarValue.STATUS_SUCCESS) {
+            model.year.value
+        } else null
 
-    private val mModelListener = OnCarDataAvailableListener<Model> {
-        telemetryHolder.updateVehicle(it)
+        telemetryHolder.updateVehicle(name, manufacturer, year)
 
-        val tlm = telemetryHolder.toTelemetry()
-        tlm?.let {
+        telemetryHolder.toTelemetry()?.let {
             telemetryCallbacks.forEach { callback ->
-                callback(tlm, null)
+                callback(it)
             }
         }
     }
@@ -70,51 +70,13 @@ object AndroidAutoTelemetryObserver {
         }
     }
 
-    private val emitter = object : Runnable {
-        override fun run() {
-            val tlm = telemetryHolder.toTelemetry()
-
-            if (tlm != null) {
-                telemetryCallbacks.forEach { callback ->
-                    callback(tlm, null)
-                }
-            }
-
-            handler.postDelayed(this, BuildConfig.TELEMETRY_UPDATE_INTERVAL)
-        }
-    }
-
-    fun addListener(callback: (Telemetry?, String?) -> Unit): () -> Unit {
-        telemetryCallbacks.add(callback)
-
-
-        // start is called every time a new listener is registered, so the single shot values are still requested and returned immediately
-        try {
-            startTelemetryObserver()
-        } catch (err: Exception) {
-            callback(null, err.message)
-        }
-
-
-        return {
-            telemetryCallbacks.remove(callback)
-            if (telemetryCallbacks.isEmpty()) {
-                stopTelemetryObserver()
-            }
-        }
-    }
-
-
-    fun startTelemetryObserver(
-    ) {
-        val carContext =
-            AndroidAutoSession.Companion.getCarContext(AndroidAutoSession.Companion.ROOT_SESSION)
-                ?: throw IllegalArgumentException(
-                    "Car context not available, failed to start telemetry"
-                )
+    override fun startTelemetryObserver(): Boolean {
+        val carContext = AndroidAutoSession.getRootContext() ?: throw IllegalArgumentException(
+            "Car context not available, failed to start telemetry"
+        )
 
 
-        AndroidAutoTelemetryObserver.carContext = carContext
+        AndroidTelemetryObserver.carContext = carContext
         if (carContext.carAppApiLevel < CarAppApiLevels.LEVEL_3) {
             throw UnsupportedOperationException("Telemetry not supported for this API level ${carContext.carAppApiLevel}")
         }
@@ -133,13 +95,10 @@ object AndroidAutoTelemetryObserver {
         } catch (_: NullPointerException) {
         }
 
-        if (isRunning) {
-            // we stop here to not re-register multiple listeners, only the single shot values can be requested multiple times by registering another tlm listener on RN side
-            Log.d(
-                AndroidAutoTelemetryObserver.javaClass.name,
-                "Telemetry observer is already running"
-            )
-            return
+        if (isObserverRunning) {
+            // we stop here to not re-register multiple listeners
+            // only the single shot values can be requested multiple times by registering another tlm listener on RN side
+            return false
         }
 
         try {
@@ -160,19 +119,17 @@ object AndroidAutoTelemetryObserver {
         } catch (_: NullPointerException) {
         }
 
-        handler.post(emitter)
-
-        isRunning = true
 
-        Log.d(AndroidAutoTelemetryObserver.javaClass.name, "Telemetry observer started")
+        isObserverRunning = true
+        return true
     }
 
-    fun stopTelemetryObserver() {
-        if (!isRunning) {
+    override fun stopTelemetryObserver() {
+        if (!isObserverRunning) {
             return
         }
 
-        isRunning = false
+        isObserverRunning = false
 
         carContext?.let {
             val carHardwareManager = it.getCarService(
@@ -195,7 +152,5 @@ object AndroidAutoTelemetryObserver {
             } catch (_: SecurityException) {
             }
         }
-
-        handler.removeCallbacks(emitter)
     }
-}
+}

package/android/src/automotive/AndroidManifest.xml

@@ -0,0 +1,91 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <uses-feature
+        android:name="android.hardware.type.automotive"
+        android:required="true" />
+
+    <uses-feature
+        android:name="android.software.car.templates_host"
+        android:required="true" />
+
+    <uses-permission android:name="androidx.car.app.NAVIGATION_TEMPLATES" />
+    <uses-permission android:name="androidx.car.app.MAP_TEMPLATES" />
+    <uses-permission android:name="androidx.car.app.ACCESS_SURFACE" />
+
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
+
+    <uses-permission android:name="android.permission.WAKE_LOCK" />
+
+
+    <!-- Android Automotive specific permissions -->
+    <uses-permission android:name="android.car.permission.CAR_ENERGY" />
+    <uses-permission android:name="android.car.permission.CAR_ENERGY_PORTS" />
+    <uses-permission android:name="android.car.permission.CAR_EXTERIOR_ENVIRONMENT" />
+    <uses-permission android:name="android.car.permission.CAR_IDENTIFICATION" />
+    <uses-permission android:name="android.car.permission.CAR_INFO" />
+    <uses-permission android:name="android.car.permission.CAR_POWERTRAIN" />
+    <uses-permission android:name="android.car.permission.CAR_SPEED" />
+
+    <application>
+        <activity
+            android:name="androidx.car.app.activity.CarAppActivity"
+            android:exported="true"
+            android:launchMode="singleTask"
+            android:theme="@android:style/Theme.DeviceDefault.NoActionBar">
+
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+
+                <category android:name="android.intent.category.LAUNCHER" />
+                <category android:name="android.intent.category.APP_MAPS" />
+            </intent-filter>
+
+            <intent-filter>
+                <action android:name="androidx.car.app.action.NAVIGATE" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <data android:scheme="geo" />
+            </intent-filter>
+
+            <meta-data
+                android:name="distractionOptimized"
+                android:value="true" />
+
+        </activity>
+
+        <service
+            android:name="com.margelo.nitro.swe.iternio.reactnativeautoplay.AndroidAutoService"
+            android:exported="true"
+            android:foregroundServiceType="location">
+            <intent-filter>
+                <action android:name="androidx.car.app.CarAppService" />
+
+                <category android:name="androidx.car.app.category.NAVIGATION" />
+                <category android:name="androidx.car.app.category.FEATURE_CLUSTER" />
+            </intent-filter>
+            <intent-filter>
+                <action android:name="androidx.car.app.action.NAVIGATE" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <data android:scheme="geo" />
+            </intent-filter>
+        </service>
+
+        <service android:name="com.margelo.nitro.swe.iternio.reactnativeautoplay.HeadlessTaskService" />
+
+        <provider
+            android:name="com.margelo.nitro.swe.iternio.reactnativeautoplay.ActivityRenderStateProvider"
+            android:authorities="${applicationId}.ActivityRenderStateProvider"
+            android:exported="false" />
+
+        <meta-data
+            android:name="com.android.automotive"
+            android:resource="@xml/automotive_app_desc" />
+        <meta-data
+            android:name="androidx.car.app.minCarApiLevel"
+            android:value="1" />
+    </application>
+
+</manifest>