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.

• exitApp()
• canOpenUrl(...)
• openUrl(...)
• getState()
• getLaunchUrl()
• addListener(...)
• addListener(...)
• addListener(...)
• addListener(...)
• removeAllListeners()
• Interfaces

Note about canOpenUrl

To use canOpenUrl, you need to set the URL schemes your app will query for in LSApplicationQueriesSchemes in Info.plist.

Read more about LSApplicationQueriesSchemes and configuring Info.plist.

Example

import { Plugins, AppState } from '@capacitor/core';

const { App } = Plugins;

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

var ret = await App.canOpenUrl({ url: 'com.getcapacitor.myapp' });
console.log('Can open url: ', ret.value);

ret = await App.openUrl({
  url: 'com.getcapacitor.myapp://page?id=ionicframework',
});
console.log('Open url response: ', ret);

ret = await App.getLaunchUrl();
if (ret && ret.url) {
  console.log('App opened with URL: ' + ret.url);
}
console.log('Launch url: ', ret);

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

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

Android: Use appRestoredResult

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.

API

exitApp()

exitApp() => never

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

Returns: never

---

canOpenUrl(...)

canOpenUrl(options: { url: string; }) => Promise<{ value: boolean; }>

Check if an app can be opened with the given URL

Param	Type
options	{ url: string; }

Returns: Promise<{ value: boolean; }>

---

openUrl(...)

openUrl(options: { url: string; }) => Promise<{ completed: boolean; }>

Open an app with the given URL

Param	Type
options	{ url: string; }

Returns: Promise<{ completed: boolean; }>

---

getState()

getState() => Promise<AppState>

Gets the current app state

Returns:

Promise<AppState>

---

getLaunchUrl()

getLaunchUrl() => Promise<AppLaunchUrl>

Get the URL the app was launched with, if any

Returns:

Promise<AppLaunchUrl>

---

addListener(...)

addListener(eventName: 'appStateChange', listenerFunc: (state: AppState) => void) => PluginListenerHandle

Listen for changes in the App's active state (whether the app is in the foreground or background)

Param	Type
eventName	"appStateChange"
listenerFunc	(state: AppState) => void

Returns:

PluginListenerHandle

---

addListener(...)

addListener(eventName: 'appUrlOpen', listenerFunc: (data: AppUrlOpen) => void) => 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	(data: AppUrlOpen) => void

Returns:

PluginListenerHandle

---

addListener(...)

addListener(eventName: 'appRestoredResult', listenerFunc: (data: AppRestoredResult) => void) => 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.

Param	Type
eventName	"appRestoredResult"
listenerFunc	(data: AppRestoredResult) => void

Returns:

PluginListenerHandle

---

addListener(...)

addListener(eventName: 'backButton', listenerFunc: (data: AppUrlOpen) => void) => 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	(data: AppUrlOpen) => void

Returns:

PluginListenerHandle

---

removeAllListeners()

removeAllListeners() => void

Remove all native listeners for this plugin

---

Interfaces

AppState

Prop	Type
isActive	boolean

AppLaunchUrl

Prop	Type
url	string

PluginListenerHandle

Prop	Type
remove	() => void

AppUrlOpen

Prop	Type	Description
url	string	The URL the app was opened with
iosSourceApplication	any	The source application opening the app (iOS only) https://developer.apple.com/documentation/uikit/uiapplicationopenurloptionskey/1623128-sourceapplication
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

AppRestoredResult

Prop	Type	Description
pluginId	string	The pluginId this result corresponds to. For example, Camera.
methodName	string	The methodName this result corresponds to. For example, getPhoto
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
success	boolean	Boolean indicating if the plugin call succeeded
error	{ message: string; }	If the plugin call didn't succeed, it will contain the error message