@capacitor-firebase/app-check

Unofficial Capacitor plugin for Firebase App Check.[^1]

Compatibility

| Plugin Version | Capacitor Version | Status |
| -------------- | ----------------- | -------------- |
| 8.x.x | >=8.x.x | Active support |
| 7.x.x | 7.x.x | Deprecated |
| 6.x.x | 6.x.x | Deprecated |
| 5.x.x | 5.x.x | Deprecated |

Installation

``bash
npm install @capacitor-firebase/app-check firebase
npx cap sync
`

Add Firebase to your project if you haven't already (Android / iOS / Web).

$3

See Set up your Firebase project and follow the instructions to set up your app correctly.

#### Variables

If needed, you can define the following project variable in your app’s variables.gradle file to change the default version of the dependency:

- $firebaseAppCheckPlayIntegrityVersion version of com.google.firebase:firebase-appcheck-playintegrity (default: 19.0.1)
- $firebaseAppCheckDebugVersion version of com.google.firebase:firebase-appcheck-debug (default: 19.0.1)

This can be useful if you encounter dependency conflicts with other plugins in your project.

$3

On iOS 14 and later, see Set up your Firebase project and follow the instructions to set up your app correctly.

On iOS 13, see Set up your Firebase project and follow the instructions to set up your app correctly.

Make sure that the private key (\*.p8) you upload to Firebase has DeviceCheck selected as a service.

$3

See Set up your Firebase project and follow the instructions to set up your app correctly.

Configuration

No configuration required for this plugin.

Firebase JavaScript SDK

Here you can find information on how to use the plugin with the Firebase JS SDK.

Demo

A working example can be found here: robingenz/capacitor-firebase-plugin-demo

Usage

`typescript
import { FirebaseAppCheck } from '@capacitor-firebase/app-check';
import { ReCaptchaV3Provider } from '@capacitor-firebase/app-check';
import { Capacitor } from '@capacitor/core';

const initialize = async () => {
await FirebaseAppCheck.initialize({
provider: Capacitor.getPlatform() === 'web' ? new ReCaptchaV3Provider('myKey') : undefined,
});
};

const getToken = async () => {
const { token } = FirebaseAppCheck.getToken({
forceRefresh: false,
});
return token;
};

const setTokenAutoRefreshEnabled = async () => {
await FirebaseAppCheck.setTokenAutoRefreshEnabled({ enabled: true });
};

const addTokenChangedListener = async () => {
await FirebaseAppCheck.addListener('tokenChanged', event => {
console.log('tokenChanged', { event });
});
};

const removeAllListeners = async () => {
await FirebaseAppCheck.removeAllListeners();
};
`

API

* getToken(...)
* initialize(...)
* setTokenAutoRefreshEnabled(...)
* addListener('tokenChanged', ...)
* removeAllListeners()
* Interfaces
* Type Aliases

$3

`typescript
getToken(options?: GetTokenOptions | undefined) => Promise
`

Get the current App Check token.

| Param | Type |
| ------------- | ----------------------------------------------------------- |
| options | GetTokenOptions |

Returns: Promise<GetTokenResult>

Since: 1.3.0

--------------------

$3

`typescript
initialize(options?: InitializeOptions | undefined) => Promise
`

Activate App Check for the given app.
Can be called only once per app.

| Param | Type |
| ------------- | --------------------------------------------------------------- |
| options | InitializeOptions |

Since: 1.3.0

--------------------

$3

`typescript
setTokenAutoRefreshEnabled(options: SetTokenAutoRefreshEnabledOptions) => Promise
`

Set whether the App Check token should be refreshed automatically or not.

| Param | Type |
| ------------- | ----------------------------------------------------------------------------------------------- |
| options | SetTokenAutoRefreshEnabledOptions |

Since: 1.3.0

--------------------

$3

`typescript
addListener(eventName: 'tokenChanged', listenerFunc: TokenChangedListener) => Promise
`

Called when the App Check token changed.

| Param | Type |
| ------------------ | --------------------------------------------------------------------- |
| eventName | 'tokenChanged' |
| listenerFunc | TokenChangedListener |

Returns: Promise<PluginListenerHandle>

Since: 1.3.0

--------------------

$3

`typescript
removeAllListeners() => Promise
`

Remove all listeners for this plugin.

Only available for Web.

Since: 1.3.0

--------------------

$3


#### GetTokenResult

| Prop | Type | Description | Since |
| ---------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------- | ----- |
| token | string | The App Check token in JWT format. | 1.3.0 |
| expireTimeMillis | number | The timestamp after which the token will expire in milliseconds since epoch. Only available for Android and iOS. | 1.3.0 |


#### GetTokenOptions

| Prop | Type | Description | Default | Since |
| ------------------ | -------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------ | ----- |
| forceRefresh | boolean | If true, will always try to fetch a fresh token. If false, will use a cached token if found in storage. | false | 1.3.0 |


#### InitializeOptions

| Prop | Type | Description | Default | Since |
| ------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ----- |
| debug | boolean | If true, the debug provider is used. ⚠️ Attention: The debug provider allows access to your Firebase resources from unverified devices. Don't use the debug provider in production builds of your app, and don't share your debug builds with untrusted parties. ⚠️ Deprecated: Use debugToken instead. This option will be removed in the next major version. Read more: https://firebase.google.com/docs/app-check/web/debug-provider | false | 1.3.0 |
| debugToken | string \| boolean | If true, the debug provider is used. On Web, you can also set a predefined debug token string instead of true. On Android and iOS, you have to use environment variables for this. ⚠️ Attention: The debug provider allows access to your Firebase resources from unverified devices. Don't use the debug provider in production builds of your app, and don't share your debug builds with untrusted parties. | false | 7.1.0 |
| isTokenAutoRefreshEnabled | boolean | If true, the SDK automatically refreshes App Check tokens as needed. | false | 1.3.0 |
| provider | any | The provider to use for App Check. Must be an instance of ReCaptchaV3Provider, ReCaptchaEnterpriseProvider, or CustomProvider. Only available for Web. | ReCaptchaV3Provider | 7.1.0 |
| siteKey | string | The reCAPTCHA v3 site key (public key). This option is ignored when provider is set. Only available for Web. | | 1.3.0 |


#### SetTokenAutoRefreshEnabledOptions

| Prop | Type | Description | Since |
| ------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----- |
| enabled | boolean | If true, the SDK automatically refreshes App Check tokens as needed. This overrides any value set during initializeAppCheck(). | 1.3.0 |


#### PluginListenerHandle

| Prop | Type |
| ------------ | ----------------------------------------- |
| remove | () => Promise<void> |


#### TokenChangedEvent

| Prop | Type | Description | Since |
| ----------- | ------------------- | ---------------------------------- | ----- |
| token | string | The App Check token in JWT format. | 1.3.0 |

$3


#### TokenChangedListener

Callback to receive the token change event.

(event: TokenChangedEvent): void

Testing

$3

Follow these steps to test your implementation on a real device:

1. Start your app on the Android device.
1. Run the following command to grab your temporary secret from the android logs:

`
adb logcat | grep DebugAppCheckProvider
`

The output should look like this:

`
D DebugAppCheckProvider: Enter this debug secret into the allow list in
the Firebase Console for your project: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
``

1. Next, open the App Check project in the Firebase Console and select Manage debug tokens from the overflow menu of your app. Then, register the debug secret from the output.

Changelog

See CHANGELOG.md.

License

See LICENSE.

[^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Google LLC or any of their affiliates or subsidiaries.