Handling Vega App Backgrounding/Foregrounding

Vega Open Beta Knowledge Base
1

There are various different use cases in which an app running on a Vega device can be moved into background and foreground. We would like to offer this guidance to developers on the correct way of simulating foregrounding/backgrounding of your app.

This scenario will be useful in testing warm launch scenarios of your apps as well as understanding actions that need to be taken by developers when your apps are backgrounded.

FG/BG Use Cases:

  • 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 (Netflix, Peacock, etc.)
  • 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.

LCM / App Framework

The Vega Lifecycle Manager (LCM) component in a Vega device is responsible for handling movement of the apps to foreground/background. LCM works based on calls from the Fire TV home launcher (SMP lighthouse launcher app) through API/msg mechanism.

Mechanism for Simulating FG/BG of Apps

Let’s explore different mechanisms that can be used by developers to simulate FG/BG of your apps.

Option 1:

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

Send App to Background

vda shell vlcm launch-app os://home

This will launch 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.

vda shell vlcm list

Option 2:

Launching another application when current app is in foreground will also push the current app to be moved to background. Note that you can only simulate this if you have multiple applications installed and your app and this does not include any system services/apps.

Launch another app:

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

Option 3:

You can send your application to the background by invoking Alexa to search for catalog titles. Current software of Vega device includes 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.

:light_bulb: NOTE: If your app has completed Content Launcher integration, then Alexa search functionality can also trigger in-app search (Implicit/Explicit search using Alexa). This should be avoided to test backgrounding of the app.

Bring the app to foreground again

This is equivalent to a warm launch — the app is already running in the background.

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

Mechanism to Handle App State

Kepler Applications 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.

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;

Cleanup Within Your App when Pushed to the Background:

When your app is pushed to the background the app should perform some cleanup tasks in order to make sure that there is minimal impact to the user experience as well as app resources are utilized optimally. Below are some of the recommendations on what the app should do when pushed to background:

  • Stop any ongoing content playback - this is essential so as to make sure that the media decoders are not blocked and app is releasing playback resources when not showing any content to the user
  • Updating the app lifecycle state - if the app is maintaining any lifecycle states to control functionality based on foreground or background state then this should be updated
  • Memory optimization - your apps should release any memory allocated that is no longer needed when pushed to the background
  • Warm start - If the app is relaunched after it has been in the background, it should perform a warm start to resume from the steady state it was maintaining while in background.

Further reading

For more info on AppState and usage, see the AppState documentation.

For apps with multiple interactive components, also see KeplerAppState which provides Vega-specific app state handling per component.

Last updated: Mar 9, 2026