expo-live-activity

Live Activity views support image display via two specific fields in the state (or content-state) object:

1. imageName
2. dynamicIslandImageName

Supported Values:

• Asset Name: A string mapping to a local asset name.
• Remote URL: A URL to a remote image.

Important Requirements for Remote URLs:

• Currently, remote URLs are only supported via the API (push notification support for remote URLs is planned).
• Using remote URLs requires adding the "App Groups" capability to both the "main app" and "Live Activity" targets.

You can pass a deepLinkUrl in the config object when calling startActivity. This allows users to tap the Live Activity to navigate to a specific screen in your app.

If using @react-navigation, it is recommended to use Linking.createURL('') to handle prefixes. The URL scheme is automatically pulled from the scheme field in app.json or falls back to the ios.bundleIdentifier.

import { Linking } from 'react-native';
import * as LiveActivity from 'expo-live-activity';

const prefix = Linking.createURL('');

// ... inside your component
LiveActivity.startActivity(state, {
  deepLinkUrl: '/order',
});

By default, Live Activities can only be started or updated via the local API. To enable starting or updating Live Activities via push notifications, you must add the enablePushNotifications flag to your plugin configuration in app.json or app.config.ts.

Note: The PushToStart feature requires iOS 17.2 or higher.

{
  "plugins": [
    [
      "expo-live-activity",
      {
        "enablePushNotifications": true
      }
    ]
  ]
}

To use expo-live-activity, you must use Expo DevClient as it is not supported in Expo Go. This module is intended for iOS devices only (iOS 16.2+).

1. Install the package:

npm install expo-live-activity

2. Configure the Config Plugin in your app.json or app.config.js:

{
  "expo": {
    "plugins": ["expo-live-activity"]
  }
}

3. If you need to update Live Activities via push notifications, enable the option:

{
  "expo": {
    "plugins": [
      [
        "expo-live-activity",
        {
          "enablePushNotifications": true
        }
      ]
    ]
  }
}

4. Place images for Live Activities in the assets/liveActivity folder. Note that images must be smaller than 4KB due to iOS limitations.

5. Run prebuild to generate the necessary iOS targets:

npx expo prebuild --clean

The LiveActivityState object defines the content displayed in the Live Activity.

Fields include:

• title: The main heading.
• subtitle: Optional secondary text.
• progressBar: An object representing progress. It can be one of several shapes:
  • { date: number } (for a countdown/timer based on a timestamp)
  • { progress: number } (a 0.0 to 1.0 value)
  • { elapsedTimer: { startDate: number } } (timer based on start time)
  • { currentStep: number, totalSteps: number } (step-based progress)
• imageName: Name of the image to display.
• dynamicIslandImageName: Specific image for the Dynamic Island.
• smallImageName: Specific image for small views.

To enable push notification support for Live Activities in your Expo project, use the withPushNotifications config plugin. This plugin performs two critical configuration steps during the prebuild process:

1. Sets the aps-environment entitlement to development in your Entitlements.plist.
2. Sets the ExpoLiveActivity_EnablePushNotifications key to true in your Info.plist.

This is required to allow the native iOS code to receive push updates for Live Activities.

// In your app.config.js or app.json
export default {
  expo: {
    plugins: [
      [
        'expo-live-activity',
        // ... other plugin options
      ],
      'withPushNotifications' // Add this to enable push support
    ],
  },
};

The expo-module.config.json defines the native module entry points for different platforms. For expo-live-activity, the following native modules are registered:

• Apple (iOS): ExpoLiveActivityModule
• Android: expo.modules.liveactivity.ExpoLiveActivityModule

{
  "platforms": ["apple", "android", "web"],
  "apple": {
    "modules": ["ExpoLiveActivityModule"]
  },
  "android": {
    "modules": ["expo.modules.liveactivity.ExpoLiveActivityModule"]
  }
}

The withUnsupportedOS config plugin allows you to control how the library behaves on unsupported operating systems by setting a boolean flag in the Info.plist.

When silentOnUnsupportedOS is set to true, the library will suppress warnings or errors related to unsupported OS versions. This value is written to the ExpoLiveActivity_SilentOnUnsupportedOS key in your app's Info.plist during the Expo prebuild process.

// Example usage in app.config.js or app.json
export default {
  expo: {
    plugins: [
      [
        "expo-live-activity",
        {
          silentOnUnsupportedOS: true
        }
      ]
    ]
  }
};

The LiveActivityConfig object allows you to customize the visual properties of the Live Activity.

Key configuration options include:

• Colors: backgroundColor, titleColor, subtitleColor, progressViewTint, progressViewLabelColor, progressSegmentActiveColor, progressSegmentInactiveColor.
• Layout: padding (can be a number or an object), imagePosition ('left' | 'right' | 'leftStretch' | 'rightStretch'), imageAlign ('top' | 'center' | 'bottom').
• Images: imageSize and smallImageSize (supports number or percentage strings like '50%'), contentFit ('cover' | 'contain' | 'fill' | 'none' | 'scale-down').
• Other: deepLinkUrl, timerType ('circular' | 'digital').

When using the expo-live-activity Config Plugin in your app.json or app.config.js, you can provide an options object to customize its behavior.

Supported options:

• enablePushNotifications: (boolean, optional) Enables support for push notification tokens used to update Live Activities.
• silentOnUnsupportedOS: (boolean, optional) If true, the plugin will fail silently on operating systems that do not support Live Activities (e.g., Android) instead of throwing an error during prebuild.

{
  "expo": {
    "plugins": [
      [
        "expo-live-activity",
        {
          "enablePushNotifications": true,
          "silentOnUnsupportedOS": true
        }
      ]
    ]
  }
}