Transition App State between Background and Foreground

There are various use cases to move your app between background and foreground states. Testing this transition helps you understand warm launch scenarios of your apps as well as actions you need to take when your apps are in the background. This page shows you how to simulate transitions between foreground and background of your app.

Common use cases

Here are some common use cases for testing foreground and background transitions:

• Pressing the “home” button while the app is running (clears backstack)
• Deep linking into another app (backstack doesn’t wipe)
• Pressing a dedicated app launch button
• Pressing the Alexa voice button (overlays on top of the app)

The backstack behavior will decide if the user can enter back into the backgrounded app by pressing back key.

Lifecycle manager and app framework

The Vega Lifecycle Manager (LCM) component in a Vega device is responsible for handling movement of the apps to the foreground or background. LCM will work based on call from Fire TV home launcher. You can learn more about LCM in App Management and Communication Tools.

Simulate transition between background and foreground

Let’s explore different mechanisms you can use to simulate foreground and background transitions of your apps.

Home launcher sends app to the background

This mechanism launches the Fire TV home launcher app on the Vega device, which pushes the running app in the background. This is the most common use case in real-world scenarios, where pressing home key executes the same commands to achieve the required behavior.

Send the app to background

Copy code Copied to clipboard.

vda shell vlcm launch-app os://home

This command launches the home launcher app. Pressing home RCU button performs the same action as simulated by the above command.

List Apps to Check Which is Visible

You can run the command below to list all the running apps to check if your app is running in the background now.

Copy code Copied to clipboard.

vda shell vlcm list

Launch a new app while an app is in the foreground

Launching another app when current app is in foreground also pushes the current app to the background. You can only simulate this if you have multiple apps installed, not including any system services.

Copy code Copied to clipboard.

vda shell vlcm launch-app orpheus://<appID for another app>

Invoke Alexa to send an app to the background

You can send your app to the background by invoking Alexa to search for catalog titles. Vega devices include implementation of universal search, which means that when the search results are invoked, the app in the foreground will be pushed to the background.

This can be done by pressing and holding “voice” key on the RCU and searching for any content.

Bring the app to foreground again

Bringing your app back to the foreground is similar to launching the app again, but in warm start (for example, when the app runs in the background). Run the following command to bring the app to the foreground.

Copy code Copied to clipboard.

vda shell vlcm launch-app orpheus://<appID>

Mechanisms to handle app state

Vega apps have access to AppState through React Native APIs. This can be used to check the current state of the app: “active” or “background”. The app can also register for “change” event listener to get notified of the AppState.

Copy code Copied to clipboard.

import React, { useRef, useState, useEffect } from 'react';
import { AppState, StyleSheet, Text, View } from 'react-native';

const AppStateExample = () => {
  const appState = useRef(AppState.currentState);
  const [appStateVisible, setAppStateVisible] = useState(appState.current);

  useEffect(() => {
    const subscription = AppState.addEventListener('change', nextAppState => {
      console.log('Current AppState is:', appState.current);
      console.log('Next AppState is:', nextAppState);
      if (
        appState.current.match(/inactive|background/) &&
        nextAppState === 'active'
      ) {
        console.log('App has come to the foreground!');
      }

      appState.current = nextAppState;
      setAppStateVisible(appState.current);
      console.log('AppState:', appState.current);
    });

    return () => {
      subscription.remove();
    };
  }, []);

  return (
    <View style={styles.container}>
      <Text>Current state is: {appStateVisible}</Text>
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
});

export default AppStateExample;

You can learn more about AppState in the React Native for Vega documentation.

Cleanup your app when pushed to the background

When your app is pushed to the background, the app should perform some cleanup tasks to make sure that there is minimal impact to the user experience and ensure app resources are utilized optimally. Here are some of the recommendations on what the app should do when pushed to background:

• Stop any ongoing content playback - this is essential to make sure the media decoders are not blocked and the app releases playback resources when not showing any content to the user.
• Updating the app lifecycle state - if the app maintains any lifecycle states to control functionality with foreground or background usage, it should be updated.
• Memory optimization - your apps should release any memory allocated which is no longer needed when pushed to the background.
• Warm start - if you relaunch the app after it has been in the background, it should perform a warm start to resume from the steady state it maintained while in background.

Last updated: Oct 07, 2025