Skip to main content

Permissions Runtime Behavior

1. Overview​

The React Native and Expo modules do not implement their own permission logic. All permission handling, background execution rules, and runtime behavior are fully delegated to the underlying native SDKs.

As a result:

  • Permission requirements are platform-specific
  • Permission behavior follows native system rules
  • Permission change detection is handled natively
  • The JavaScript layer exposes events emitted by the native SDKs

This document focuses on:

  • how permission-related events are exposed to JavaScript
  • how to react to those events using listeners

2. Permission change handling in React Native​

Unlike the native SDKs, the React Native and Expo modules do not implement their own permission change detection logic.

Permission changes are detected entirely by the underlying native SDKs, using platform-specific mechanisms:

  • iOS evaluates permission state when the application becomes active and exposes a fixed set of permission-related callbacks
  • Android does not emit permission-related events. Permissions are validated when the telematics service is started

The modules act strictly as a forwarding layer:

  • they listen to permission-related callbacks emitted by the native SDKs
  • they forward those native events to JavaScript
  • they do not normalize or reinterpret native behavior

As a result:

  • the type, timing, and semantics of events are platform-dependent
  • the JavaScript layer only exposes what the native SDK provides
  • permission behavior differs between iOS and Android by design

On iOS, the modules forward the three permission-related callbacks exposed by the iOS SDK as JavaScript events.

The following events are exposed:

  • Permissions missing (addPermissionsMissingListener)
  • Permissions lost while running (addPermissionsLostWhileRunningListener)
  • Telemetry gap detected (addTelemetryGapDetectedListener)

Each event is emitted under the same conditions as described in the iOS SDK documentation.

For a detailed explanation of when these events are triggered and what they represent, refer to:

iOS SDK – Permission Runtime Behavior → Callbacks exposed by the SDK

2.2 Android behavior​

The Android SDK does not emit permission-related events, so these listeners are never called on Android.

On Android, the permissions and the battery optimization state are validated when the telematics service is started: if any requirement is missing, startTelematicsService is rejected and telemetry does not start. To keep the application consistent with the SDK requirements, check the permission state with checkPermissions() and isBatteryOptimizationDeactivated(), for example before starting the service and whenever the application returns to the foreground.

For the list of required permissions and system settings, refer to:

Android SDK – Permissions Setup

3. Usage​

This section shows how to handle permission changes in a React Native or Expo application.

3.1 iOS​

The example below demonstrates how to listen to the iOS permission-related events forwarded by the module. Each listener function returns a subscription; call remove() when the listener is no longer needed.

The lostAt, from and to values are epoch timestamps in milliseconds.

import {
  addPermissionsMissingListener,
  addPermissionsLostWhileRunningListener,
  addTelemetryGapDetectedListener,
} from '@driviantelematics/telematics-sdk-rn';

const subMissing = addPermissionsMissingListener(({ missingPermissions }) => {
  if (missingPermissions.length === 0) {
    // All required permissions are now granted
  } else {
    // One or more mandatory permissions are missing
  }
});

const subLost = addPermissionsLostWhileRunningListener(({ lostAt, missingPermissions }) => {
  // Handle permissions lost while telemetry was running
});

const subGap = addTelemetryGapDetectedListener(({ from, to }) => {
  // Handle telemetry interruption
});

// Remember to remove listeners when no longer needed
subMissing.remove();
subLost.remove();
subGap.remove();

3.2 Android​

The example below checks the permission state when the application returns to the foreground.

import { AppState, Platform } from 'react-native';
import { checkPermissions, isBatteryOptimizationDeactivated } from '@driviantelematics/telematics-sdk-rn';

const subscription = AppState.addEventListener('change', async (state) => {
  if (Platform.OS !== 'android' || state !== 'active') {
    return;
  }

  const missingPermissions = await checkPermissions();
  const batteryOk = await isBatteryOptimizationDeactivated();

  if (missingPermissions.length > 0 || !batteryOk) {
    // Ask the user to grant the missing permissions or disable battery optimization
  }
});

// Remember to remove the listener when no longer needed
subscription.remove();

Notes​

  • The modules do not request permissions on their own.
  • Permission changes are detected only when the native SDK is able to execute.
  • Background permission changes may not be detected immediately, depending on platform behavior.
  • Always refer to the platform-specific documentation for detailed permission behavior.