@capacitor/app

What is @capacitor/app?

@capacitor/app is a Capacitor plugin that provides various functionalities related to the app lifecycle and state. It allows developers to handle app state changes, manage app URLs, and more.

What are @capacitor/app's main functionalities?

App State

This feature allows you to listen for changes in the app's state, such as when the app becomes active or goes into the background.

import { App } from '@capacitor/app';

App.addListener('appStateChange', (state) => {
  console.log('App state changed. Is active:', state.isActive);
});

App URL Open

This feature allows you to handle URLs that open your app, which is useful for deep linking.

import { App } from '@capacitor/app';

App.addListener('appUrlOpen', (data) => {
  console.log('App opened with URL:', data.url);
});

App Restored Result

This feature allows you to handle the result when your app is restored from a terminated state.

import { App } from '@capacitor/app';

App.addListener('appRestoredResult', (data) => {
  console.log('App restored with result:', data);
});

Get Launch URL

This feature allows you to get the URL that was used to launch the app.

import { App } from '@capacitor/app';

App.getLaunchUrl().then((data) => {
  console.log('App launched with URL:', data.url);
});

Minimize App

This feature allows you to programmatically minimize the app.

import { App } from '@capacitor/app';

App.minimizeApp();

Other packages similar to @capacitor/app

cordova-plugin-app-event

cordova-plugin-app-event is a Cordova plugin that provides event listeners for app lifecycle events. It offers similar functionalities for handling app state changes and URL events. However, it is specific to Cordova and may not be as integrated with modern frameworks like Capacitor.

expo-app-loading

expo-app-loading is an Expo package that helps manage the app loading state. While it does not provide the full range of functionalities of @capacitor/app, it is useful for managing the app's loading state and ensuring that the app is fully loaded before rendering. It is specific to Expo and React Native.

README

@capacitor/app

The App API handles high level App state and events. For example, this API emits events when the app enters and leaves the foreground, handles deeplinks, opens other apps, and manages persisted plugin state.

Install

npm install @capacitor/app
npx cap sync

iOS

For being able to open the app from a custom scheme you need to register the scheme first. You can do it by editing the Info.plist file and adding this lines.

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>com.getcapacitor.capacitor</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>mycustomscheme</string>
    </array>
  </dict>
</array>

Android

For being able to open the app from a custom scheme you need to register the scheme first. You can do it by adding this lines inside the activity section of the AndroidManifest.xml.

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="@string/custom_url_scheme" />
</intent-filter>

custom_url_scheme value is stored in strings.xml. When the Android platform is added, @capacitor/cli adds the app's package name as default value, but can be replaced by editing the strings.xml file.

Example

import { App } from '@capacitor/app';

App.addListener('appStateChange', ({ isActive }) => {
  console.log('App state changed. Is active?', isActive);
});

App.addListener('appUrlOpen', data => {
  console.log('App opened with URL:', data);
});

App.addListener('appRestoredResult', data => {
  console.log('Restored state:', data);
});

const checkAppLaunchUrl = async () => {
  const { url } = await App.getLaunchUrl();

  console.log('App opened with URL: ' + url);
};

API

• exitApp()
• getInfo()
• getState()
• getLaunchUrl()
• minimizeApp()
• addListener('appStateChange', ...)
• addListener('pause', ...)
• addListener('resume', ...)
• addListener('appUrlOpen', ...)
• addListener('appRestoredResult', ...)
• addListener('backButton', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

exitApp()

exitApp() => Promise<void>

Force exit the app. This should only be used in conjunction with the backButton handler for Android to exit the app when navigation is complete.

Ionic handles this itself so you shouldn't need to call this if using Ionic.

Since: 1.0.0

getInfo()

getInfo() => Promise<AppInfo>

Return information about the app.

Returns: Promise<AppInfo>

Since: 1.0.0

getState()

getState() => Promise<AppState>

Gets the current app state.

Returns: Promise<AppState>

Since: 1.0.0

getLaunchUrl()

getLaunchUrl() => Promise<AppLaunchUrl | undefined>

Get the URL the app was launched with, if any.

Returns: Promise<AppLaunchUrl>

Since: 1.0.0

minimizeApp()

minimizeApp() => Promise<void>

Minimizes the application.

Only available for Android.

Since: 1.1.0

addListener('appStateChange', ...)

addListener(eventName: 'appStateChange', listenerFunc: StateChangeListener) => Promise<PluginListenerHandle>

Listen for changes in the app or the activity states.

On iOS it's fired when the native UIApplication.willResignActiveNotification and UIApplication.didBecomeActiveNotification events get fired. On Android it's fired when the Capacitor's Activity onResume and onStop methods gets called. On Web it's fired when the document's visibilitychange gets fired.

Param	Type
eventName	'appStateChange'
listenerFunc	StateChangeListener

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('pause', ...)

addListener(eventName: 'pause', listenerFunc: () => void) => Promise<PluginListenerHandle>

Listen for when the app or the activity are paused.

On iOS it's fired when the native UIApplication.didEnterBackgroundNotification event gets fired. On Android it's fired when the Capacitor's Activity onPause method gets called. On Web it's fired when the document's visibilitychange gets fired and document.hidden is true.

Param	Type
eventName	'pause'
listenerFunc	() => void

Returns: Promise<PluginListenerHandle>

Since: 4.1.0

addListener('resume', ...)

addListener(eventName: 'resume', listenerFunc: () => void) => Promise<PluginListenerHandle>

Listen for when the app or activity are resumed.

On iOS it's fired when the native UIApplication.willEnterForegroundNotification event gets fired. On Android it's fired when the Capacitor's Activity onResume method gets called, but only after resume has fired first. On Web it's fired when the document's visibilitychange gets fired and document.hidden is false.

Param	Type
eventName	'resume'
listenerFunc	() => void

Returns: Promise<PluginListenerHandle>

Since: 4.1.0

addListener('appUrlOpen', ...)

addListener(eventName: 'appUrlOpen', listenerFunc: URLOpenListener) => Promise<PluginListenerHandle>

Listen for url open events for the app. This handles both custom URL scheme links as well as URLs your app handles (Universal Links on iOS and App Links on Android)

Param	Type
eventName	'appUrlOpen'
listenerFunc	URLOpenListener

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('appRestoredResult', ...)

addListener(eventName: 'appRestoredResult', listenerFunc: RestoredListener) => Promise<PluginListenerHandle>

If the app was launched with previously persisted plugin call data, such as on Android when an activity returns to an app that was closed, this call will return any data the app was launched with, converted into the form of a result from a plugin call.

On Android, due to memory constraints on low-end devices, it's possible that, if your app launches a new activity, your app will be terminated by the operating system in order to reduce memory consumption.

For example, that means the Camera API, which launches a new Activity to take a photo, may not be able to return data back to your app.

To avoid this, Capacitor stores all restored activity results on launch. You should add a listener for appRestoredResult in order to handle any plugin call results that were delivered when your app was not running.

Once you have that result (if any), you can update the UI to restore a logical experience for the user, such as navigating or selecting the proper tab.

We recommend every Android app using plugins that rely on external Activities (for example, Camera) to have this event and process handled.

Param	Type
eventName	'appRestoredResult'
listenerFunc	RestoredListener

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('backButton', ...)

addListener(eventName: 'backButton', listenerFunc: BackButtonListener) => Promise<PluginListenerHandle>

Listen for the hardware back button event (Android only). Listening for this event will disable the default back button behaviour, so you might want to call window.history.back() manually. If you want to close the app, call App.exitApp().

Param	Type
eventName	'backButton'
listenerFunc	BackButtonListener

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all native listeners for this plugin

Since: 1.0.0

Interfaces

AppInfo

Prop	Type	Description	Since
name	string	The name of the app.	1.0.0
id	string	The identifier of the app. On iOS it's the Bundle Identifier. On Android it's the Application ID	1.0.0
build	string	The build version. On iOS it's the CFBundleVersion. On Android it's the versionCode.	1.0.0
version	string	The app version. On iOS it's the CFBundleShortVersionString. On Android it's package's versionName.	1.0.0

AppState

Prop	Type	Description	Since
isActive	boolean	Whether the app is active or not.	1.0.0

AppLaunchUrl

Prop	Type	Description	Since
url	string	The url used to open the app.	1.0.0

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

URLOpenListenerEvent

Prop	Type	Description	Since
url	string	The URL the app was opened with.	1.0.0
iosSourceApplication	any	The source application opening the app (iOS only) https://developer.apple.com/documentation/uikit/uiapplicationopenurloptionskey/1623128-sourceapplication	1.0.0
iosOpenInPlace	boolean	Whether the app should open the passed document in-place or must copy it first. https://developer.apple.com/documentation/uikit/uiapplicationopenurloptionskey/1623123-openinplace	1.0.0

RestoredListenerEvent

Prop	Type	Description	Since
pluginId	string	The pluginId this result corresponds to. For example, Camera.	1.0.0
methodName	string	The methodName this result corresponds to. For example, getPhoto	1.0.0
data	any	The result data passed from the plugin. This would be the result you'd expect from normally calling the plugin method. For example, CameraPhoto	1.0.0
success	boolean	Boolean indicating if the plugin call succeeded.	1.0.0
error	{ message: string; }	If the plugin call didn't succeed, it will contain the error message.	1.0.0

BackButtonListenerEvent

Prop	Type	Description	Since
canGoBack	boolean	Indicates whether the browser can go back in history. False when the history stack is on the first entry.	1.0.0

Type Aliases

StateChangeListener

(state: AppState): void

URLOpenListener

(event: URLOpenListenerEvent): void

RestoredListener

(event: RestoredListenerEvent): void

BackButtonListener

(event: BackButtonListenerEvent): void